Typography

Our typography system is designed for clarity, efficiency, and minimalism. With limited screen space in a complex developer tool, we prioritize readability and information density over decorative hierarchy.

Design Principles

Space-efficient: Default to 12px for body text to maximize content visibility
Minimal hierarchy: Only 3 header levels to avoid confusion
Weight over size: Use font-weight to create hierarchy, not excessive size changes
Functional: Every style has a clear, specific purpose

Font Family

We use Inter for all UI text due to its excellent readability at small sizes and professional appearance. For technical content (IDs, code snippets, JSON), use the system monospace font.

Text Colors

text-primary

#4a5568

Default text, body content, descriptions

text-emphasis

#2d3748

Headers, labels, emphasized content

text-secondary

#718096

Supporting information, metadata, timestamps

text-hint

#757E8F

Placeholders, tooltips, subtle hints

text-disabled

#a0aec0

Disabled states, unavailable options

Color Philosophy

We use a lighter default with a darker emphasis option to:

Reduce eye strain during extended use
Create clear visual hierarchy without relying on size
Make emphasized content truly stand out
Align with modern developer tool aesthetics

Key principle: Use text-primary for most content, reserve text-emphasis for true importance.

Type Styles

Typography Scale Overview

Style	Example	Specifications	Usage
Page Title	Home	24px (text-2xl) • 600 weight (font-semibold) • text-emphasis	Main application page titles
Title	Flow inputs	18px (text-lg) • 600 weight (font-semibold) • text-emphasis	Top-level page headings, modal titles
Section Header	Advanced settings	14px (text-sm) • 600 weight (font-semibold) • text-emphasis	Panel headers, card titles, sidebar groups
Body	Default text throughout the application	12px (text-xs) • 400 weight (font-normal) • text-primary	Descriptions, content, list items, table cells
Body Emphasized	Field name:	12px (text-xs) • 600 weight (font-semibold) • text-emphasis	Labels, form field labels, tab labels
Secondary Text	Last run 2 hours ago	12px (text-xs) • 400 weight (font-normal) • text-secondary	Supporting information, metadata, timestamps
Caption	Optional field	11px (text-2xs) • 400 weight (font-normal) • text-secondary	Helper text, table headers, annotations
Hint	Enter job name...	11px (text-2xs) • 400 weight (font-normal) • text-hint	Input placeholders, tooltips, empty states
Code/Monospace	`job_id_12345`	11px (text-2xs) • 400 weight (font-normal) • monospace (font-mono) • text-emphasis	Job IDs, code snippets, file paths, API endpoints

App Page Title

When to use: Main application page titles, primary navigation headings

class = 'font-semibold text-2xl text-emphasis';

Size: 24px (text-2xl)
Weight: 600 (font-semibold)
Color: text-emphasis
Example: "Job Orchestrator", "Flow Builder", "Resource Manager"

Page Title

When to use: Top-level page headings, modal titles, main view names

class = 'text-lg font-semibold text-emphasis';

Size: 18px (text-lg)
Weight: 600 (font-semibold)
Color: text-emphasis
Example: "Job Orchestrator Dashboard", "Edit Flow Configuration"

Section Header

When to use: Panel headers, card titles, collapsible section names, sidebar groups

class = 'text-sm font-semibold text-emphasis';

Size: 14px (text-sm)
Weight: 600 (font-semibold)
Color: text-emphasis
Example: "Active Jobs", "Configuration", "Environment Variables"

Body

When to use: Default text throughout the application - descriptions, content, list items, table cells

class = 'text-xs font-normal text-primary';

Size: 12px (text-xs)
Weight: 400 (font-normal)
Color: text-primary
Example: Form descriptions, paragraph content, dialog text

This is your default. When in doubt, use this style.

Body Emphasized

When to use: Important labels, form field labels, tab labels, emphasis within body text

class = 'text-xs font-semibold text-emphasis';

Size: 12px (text-xs)
Weight: 600 (font-semibold)
Color: text-emphasis
Example: "Job Name:", "Status:", button labels

Secondary Text

When to use: Supporting information, metadata, timestamps, status descriptions

class = 'text-xs font-normal text-secondary';

Size: 12px (text-xs)
Weight: 400 (font-normal)
Color: text-secondary
Example: "Last run 2 hours ago", "Created by John Doe", file sizes

Caption

When to use: Helper text below inputs, table column headers, inline annotations, badges

class = 'text-2xs font-normal text-secondary';

Size: 11px (text-2xs)
Weight: 400 (font-normal)
Color: text-secondary
Example: "Optional field", "Max 100 characters", column headers

Hint

When to use: Input placeholders, tooltip content, empty state messages, subtle guidance

class = 'text-2xs font-normal text-hint';

Size: 11px (text-2xs)
Weight: 400 (font-normal)
Color: text-hint
Example: "Enter job name...", "Search flows", tooltip text

Code/Monospace

When to use: Job IDs, code snippets, file paths, API endpoints, JSON keys, technical identifiers

class = 'text-2xs font-mono font-normal text-emphasis';

Size: 11px (text-2xs)
Weight: 400 (font-normal)
Color: text-emphasis
Font: System monospace
Example: job_id_12345, /api/v1/jobs, ENV_VAR_NAME

Note: Use text-emphasis for code to ensure technical values stand out and are easily scannable.

Usage Guidelines

Creating Hierarchy

Use these methods in order of preference:

Font weight - Semibold (600) for headers and emphasis, normal (400) for body
Color - Primary for main content, secondary for supporting info, hint for subtle guidance
Size - Only change size for true hierarchy levels (page title vs section header vs body)

Don't create hierarchy by:

Making text larger than 24px (except for App Page Titles)
Using more than 3 header levels
Adding excessive spacing or borders

Creating Visual Hierarchy - Priority Order

Font Weight - Use semibold (600) for emphasis
Color - Use textEmphasis for important content
Position & Spacing - Group related content, add white space
Size - Only use defined type styles, never custom sizes

❌ Don't

Increase font size to make something "stand out"
Create one-off font sizes for special cases
Use large headers in dense UI areas

✅ Do

Use font-weight to emphasize within the same size
Use textEmphasis color for important content
Add spacing around important elements

Text Casing

Primary Rule: Use Sentence Case

Use sentence case for all UI text—capitalize only the first word and proper nouns. This approach improves readability and is faster to implement consistently.

Examples:

✅ "Create new flow"
✅ "Edit Windmill resource"
❌ "Create New Flow"
❌ "SAVE CHANGES"

Casing by Component Type

Page titles and headings

Use sentence case: "Job orchestrator dashboard"

Buttons and actions

Use sentence case: "Save changes", "Delete job"

Form labels

Use sentence case: "Job name", "Resource type"

Navigation items

Use sentence case: "User settings", "Resource manager"

Error messages and notifications

Use sentence case: "Job completed successfully"

Always Capitalize

Proper nouns: Windmill, Docker, Python, GitHub
Acronyms: API, HTTP, JSON, SQL
First word of any sentence or UI element

Special Cases

Technical identifiers: Keep original casing (job_id_123, ENV_VAR)
Brand names: Follow brand guidelines (iPhone, macOS)
Abbreviations: Use standard forms (ID, URL, vs.)

Accessibility Note

Avoid ALL CAPS text except for very short labels (2-3 characters max). All caps text is slower to read and can appear aggressive to users.

Decision Tree

Not sure which style to use? Follow this:

Is it a main application page title? → Yes: App Page Title (24px, semibold) → No: Continue

Is it a page or modal title? → Yes: Page Title (18px, semibold) → No: Continue

Is it a section/panel header? → Yes: Section Header (14px, semibold) → No: Continue

Is it technical data (ID, code, path)? → Yes: Code/Monospace (11px, mono) → No: Continue

Is it a placeholder or tooltip? → Yes: Hint (11px, hint color) → No: Continue

Is it helper text or a table header? → Yes: Caption (11px, secondary color) → No: Continue

Is it metadata or supporting info? → Yes: Secondary Text (12px, secondary color) → No: Continue

Is it a label or needs emphasis? → Yes: Body Emphasized (12px, semibold weight, emphasis color) → No: Body (12px, normal, primary color) ← DEFAULT

Accessibility

All text colors meet contrast requirements on standard backgrounds
Never use font size alone to convey meaning
Ensure disabled text (text-disabled) is paired with visual disabled states

Common Mistakes

❌ Don't create custom font sizes between defined styles
✅ Do use the defined type styles

❌ Don't use Section Header inside table cells
✅ Do use Caption for table headers

❌ Don't use Body Emphasized everywhere for "importance"
✅ Do reserve it for labels and truly emphasized content

❌ Don't make job IDs or code bold/colored
✅ Do use monospace font with text-emphasis for technical identifiers

❌ Don't use text-emphasis for body paragraphs
✅ Do use text-primary for most content, text-emphasis for headers/labels

Design Principles​

Font Family​

Text Colors​

Color Philosophy​

Type Styles​

Typography Scale Overview​

App Page Title​

Page Title​

Section Header​

Body​

Body Emphasized​

Secondary Text​

Caption​

Hint​

Code/Monospace​

Usage Guidelines​

Creating Hierarchy​

Creating Visual Hierarchy - Priority Order​

❌ Don't​

✅ Do​

Text Casing​

Primary Rule: Use Sentence Case​

Casing by Component Type​

Always Capitalize​

Special Cases​

Accessibility Note​

Decision Tree​

Accessibility​

Common Mistakes​