Works  

Blocks — CBRE Build Design System 2017–2020

Blocks is CBRE Build's design system — the shared language between design, engineering, and product teams across CBRE's digital products. I authored the React component library, which was later adapted into React Native to power CBRE Tour, a mobile app used by commercial real estate appraisers in the field. Blocks is organized around three pillars — Talks, Docs, and Toolbox — covering design principles, component guidance, style standards, and dual React + HTML code samples.

1. Design Principles

Blocks is grounded in three principles that shape how the system is built, contributed to, and used by product teams.

Alignment over Assumption

Prioritize effective communication and mutual understanding before decisions.

Confirmation over Creation

Present informed, complete solutions rather than blank slates.

Progress over Perfection

Embrace iteration through real-world testing over internal debate.

2. Three Pillars

Blocks organizes its surface area into three pillars, each answering a different question teams face day-to-day.

Talks

Shared vocabulary — how design, engineering, and product discuss the same thing.

Docs

Guidelines, patterns, and usage — answers to 'what should I build?'

Toolbox

Reusable React + HTML components — answers to 'how do I build it?'

3. System Coverage

Styles, components, and patterns ship with dual React + HTML code samples so teams on either stack can consume the same source of truth.

STYLES

  • Colors & Shadows
  • Icons
  • Type (full headline + UI text scale)

PATTERNS & GOVERNANCE

  • Modals, Tabs
  • New Block Flowchart (contribution process)
  • Writing guidelines, Browser Support
  • Documentation updates guide

COMPONENTS

  • Alerts
  • Buttons
  • Checkboxes
  • Dropdowns
  • Links
  • Popovers
  • Radio Buttons
  • Text Fields
  • Toggles
  • Tooltips

4. Type Scale

A complete headline + UI text scale that governs visual hierarchy and text rendering across all CBRE Build products.

styles/type.md (scale)

Headlines        UI Text
─────────        ───────────────
Headline XL      UI Text
Headline H1      UI Link
Headline H2      UI Placeholder
Headline H3      UI Caps
Headline H4      UI Small
Headline H5      UI Small Caps

Rules:
• Headlines define document hierarchy — one H1 per view
• UI Text is the default body size across components
• UI Caps and UI Small Caps reserved for labels and metadata
• All sizes map to the same line-height rhythm for vertical alignment

5. Component Documentation Sample — Button

Every Blocks component ships with usage rules, label standards, and dual-stack code samples. Below is the condensed Button documentation.

docs/button.md

## Button

Variants
────────
• Primary    — max 2 per screen
• Secondary  — default when primary slots are used
• Danger     — destructive, irreversible, or "scary" actions only
• Dark       — for dark backgrounds / elevated surfaces

Also: text buttons with icons, icon-only buttons, and link buttons
(navigation elements styled as buttons).

Rules
─────
• Max 2 primary buttons per screen — the rest must be secondary
• Up to 3 buttons may be grouped horizontally or vertically
• Only the final button in a group may use primary styling

Label Standards
───────────────
• Sentence case only — capitalize initial word + proper nouns
• Always start with a verb describing the action
  ("Save changes", "Delete file", "Download report")
• Max 3 words

Danger Button Guidance
──────────────────────
Reserve for actions that are destructive, irreversible, or
otherwise risk losing work or time.
❌ Don't use as a generic cancel button.
❌ Don't use for reversible actions.

Code Samples
────────────
React:  <Button kind="primary">Save changes</Button>
HTML:   <button class="btn btn--primary">Save changes</button>

6. Downstream Impact — CBRE Tour (React Native)

The Blocks React component library I authored was adapted into React Native to power CBRE Tour, a field service mobile app for commercial real estate appraisers. This cross-platform journey — single source of truth in Blocks, consumed by both CBRE's web products and the Tour native app — is the system's strongest proof point: token, pattern, and component consistency from desktop web all the way to the appraiser's hand in the field.

port pattern: Blocks React → Blocks React Native

// Blocks (Web) — React
import { Button } from '@cbre-build/blocks'

<Button kind="primary" onClick={submit}>
  Save changes
</Button>

// Blocks (CBRE Tour) — React Native port
import { Button } from '@cbre-build/blocks-native'

<Button kind="primary" onPress={submit}>
  Save changes
</Button>

// Shared API surface across web + native:
//   • Same variant vocabulary (primary, secondary, danger, dark)
//   • Same label rules (sentence case, verb-first, <= 3 words)
//   • Same token references — colors, type scale, spacing
//
// Platform-specific internals (<button> vs <TouchableOpacity>,
// onClick vs onPress) are isolated behind a common interface,
// so designers and consumers think in one vocabulary.

The design system's governance model — the New Block Flowchart, writing guidelines, and documentation standards — ensured that contributions flowed back into both the web and native libraries consistently, preventing drift between platforms.

Full documentation at awesome-knuth-6f8b93.netlify.app