Getting Started

Building for the long term

Good software is not written — it is rewritten. The best systems evolve through careful iteration, not grand rewrites. Every decision you make today shapes the landscape your future self will navigate.

Core principles

When designing an interface, consider the hierarchy of attention. Users scan before they read, click before they explore, and leave before they understand. Your job is to make each of those moments count.

Design is not just what it looks like and feels like. Design is how it works.

Typography

We use three font families across the system. Each serves a distinct role:

• Besley — display and titles. A transitional serif with warm, confident character.
• Figtree — body and UI text. A geometric sans-serif that's clean and readable at every size.
• IBM Plex Mono — code, data, and labels. Tabular figures, technical precision.

Color tokens

All colors are defined as CSS custom properties and resolve automatically for light and dark themes. The system provides semantic tokens for common use cases like --destructive, --success, and --link.

Token	Light	Dark	Usage
--label	#1A1A18	#F5F5F2	Primary text
--tint	#E86420	#F07030	Brand accent, CTAs
--link	#1270B8	#1A8DE0	Inline links
--destructive	#CE2021	#E84142	Delete, errors

Implementation

The prose class wraps any block of rendered markdown and applies the full typographic scale. Headers use Besley, body uses Figtree, and code blocks use IBM Plex Mono — all automatically.

// Apply the prose styles to any container
<div class="prose">
  {{ rendered_markdown }}
</div>

// CSS custom property for tint
document.documentElement.style
  .setProperty('--tint', '#E86420');

Inline elements

Inline code like var(--systemFill) uses a subtle tint color. Bold text uses Figtree 600. Italic text uses native italic. Bold italic combines both. Strikethrough marks removed content. Links like color tokens are underlined with a translucent line that solidifies on hover.

Detailed specifications

The h5 heading uses Besley at a smaller size, bridging the gap between h4 and body text. Use it for fine-grained subsections within a longer document.

Revision History

The h6 heading switches to IBM Plex Mono uppercase with letter-spacing — ideal for metadata labels, version tags, and document annotations.

Nested lists

• Design tokens
  • Color primitives
    • Brand orange #E86420
    • Neutral grays
  • Semantic aliases
• Typography scale
  1. Display — Besley
  2. Body — Figtree
  3. Mono — IBM Plex Mono

Task list

• Define color tokens in CSS custom properties
• Set up font loading via Google Fonts
• Build typography scale for web
• Add dark-mode media query fallback
• Audit contrast ratios (WCAG AA)

Media

---

1. Define your color tokens in :root
2. Load fonts via Google Fonts (single <link> tag)
3. Apply .prose to markdown containers
4. Toggle themes with data-theme="dark"

This example demonstrates all markdown elements styled with the design language. The same visual language applies whether content is authored in a CMS, rendered from an API response, or written inline.