# Blog Typography & Content Formatting Guide

**Last Updated:** 2026-01-09

Complete reference guide for blog post typography, content formatting, and styling patterns following Ordio brand guidelines and modern UI/UX best practices.

## Overview

This guide documents the comprehensive typography system for blog posts, including heading hierarchy, text formatting, lists, block elements, and responsive design patterns. All styles follow Ordio brand guidelines and accessibility standards.

## Typography Hierarchy

### Heading System

All headings use **Gilroy Bold** font family with consistent styling:

| Level | Mobile Size      | Desktop Size    | Top Margin     | Bottom Margin   | Weight | Use Case                            |
| ----- | ---------------- | --------------- | -------------- | --------------- | ------ | ----------------------------------- |
| H1    | 2rem (32px)      | 2.75rem (44px)  | 2.5rem (40px)  | 1.25rem (20px)  | 700    | Main section headings (rarely used) |
| H2    | 1.75rem (28px)   | 2.25rem (36px)  | 2.5rem (40px)  | 1.25rem (20px)  | 700    | Major section headings              |
| H3    | 1.375rem (22px)  | 1.75rem (28px)  | 2rem (32px)    | 1rem (16px)     | 700    | Subsection headings                 |
| H4    | 1.125rem (18px)  | 1.375rem (22px) | 1.75rem (28px) | 1rem (16px)     | 600    | Minor subsections                   |
| H5    | 1rem (16px)      | 1.25rem (20px)  | 1.5rem (24px)  | 0.875rem (14px) | 600    | Small subsections                   |
| H6    | 0.9375rem (15px) | 1.125rem (18px) | 1.25rem (20px) | 0.625rem (10px) | 600    | Smallest headings (uppercase)       |

**Heading Properties**:

- Font family: `'Gilroy Bold', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif`
- Line height: 1.2-1.3 (tighter for larger headings)
- Color: `--text-primary` (#1F2937)
- First heading in content: `margin-top: 0`

### Body Text

**Paragraphs**:

- Font family: `'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif`
- Font size: `1.125rem` (18px)
- Line height: `1.75` (optimal for readability)
- Color: `--text-primary` (#1F2937)
- Bottom margin: `1.75rem` (28px)
- First paragraph after heading: `margin-top: 0`
- Last paragraph: `margin-bottom: 0`

## Spacing System

### Vertical Rhythm

Consistent spacing creates visual rhythm and improves readability:

**Spacing Scale**:

- `--blog-spacing-xs`: 0.5rem (8px)
- `--blog-spacing-sm`: 0.75rem (12px)
- `--blog-spacing-md`: 1rem (16px)
- `--blog-spacing-lg`: 1.5rem (24px)
- `--blog-spacing-xl`: 2rem (32px)
- `--blog-spacing-2xl`: 2.5rem (40px)
- `--blog-spacing-3xl`: 3rem (48px)

**Element Spacing**:

- Paragraphs: 1.75rem (28px) bottom margin
- Lists: 1.5rem (24px) top/bottom margin
- Blockquotes: 2.5rem (40px) top/bottom margin
- Code blocks: 2.5rem (40px) top/bottom margin
- Tables: 2.5rem (40px) top/bottom margin

## List Styling

### Unordered Lists (ul)

**Styling**:

- Marker: `disc` (outer level)
- Marker: `circle` (nested level)
- Marker: `square` (deep nested level)
- Left padding: `1.75rem`
- Top/bottom margin: `1.5rem`
- List item spacing: `1rem` bottom margin

**Nested Lists**:

- Additional left margin: `1.5rem`
- Reduced top/bottom margin: `0.75rem`
- Marker type changes automatically

### Ordered Lists (ol)

**Styling**:

- Marker: `decimal` (1, 2, 3...)
- Marker: `lower-alpha` (a, b, c...) - nested
- Marker: `lower-roman` (i, ii, iii...) - deep nested
- Same spacing as unordered lists
- Proper numbering appearance

**List Items (li)**:

- Bottom margin: `1rem` (16px)
- Padding left: `0.5rem`
- Line height: `1.75` (matches body text)
- Last item: `margin-bottom: 0`

**Complex List Content**:

- Paragraphs within list items: `0.75rem` bottom margin
- Headings within list items: Proper spacing maintained
- Nested lists within items: `0.75rem` top/bottom margin

## Text Formatting

### Strong/Bold Text

**Styling**:

- Font weight: `700`
- Color: `--text-primary` (#1F2937)
- Used for emphasis within content
- Distinguishable from headings

### Emphasis/Italic Text

**Styling**:

- Font style: `italic`
- Color: `--text-primary` (#1F2937)
- Can be combined with strong
- Used for emphasis, citations, foreign words

### Inline Code

**Styling**:

- Background: `#F3F4F6` (light gray)
- Border: `1px solid #E5E7EB`
- Font family: `ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace`
- Font size: `0.9375rem` (15px - 83% of body size)
- Font weight: `500`
- Padding: `0.2rem 0.5rem`
- Border radius: `0.375rem`
- Line height: `1.5`

**Within Headings**:

- Font size: `0.85em` (relative to heading)
- Lighter background and border

### Code Blocks (pre)

**Styling**:

- Background: `#1F2937` (dark gray)
- Color: `#F9FAFB` (light text)
- Padding: `1.5rem`
- Border: `1px solid #374151`
- Border radius: `0.5rem`
- Overflow: Horizontal scroll for long code
- Font: Monospace, `0.9375rem` (15px)
- Line height: `1.6`
- Margin: `2.5rem` top/bottom
- Box shadow: `var(--shadow-md)`

**Scrollbar Styling**:

- Thin scrollbar
- Dark theme colors
- Smooth scrolling on touch devices

**Code within pre**:

- Background: Transparent
- No border or padding
- Color: `#F9FAFB`
- White-space: `pre`
- No word wrap

## Block Elements

### Blockquotes

**Styling**:

- Border left: `4px solid var(--ordio-blue)` (#4D8EF3)
- Background: `var(--ordio-blue-light)` (#EFF6FF)
- Padding: `1.25rem 1.5rem`
- Font size: `1.25rem` (20px)
- Font style: `italic`
- Line height: `1.7`
- Color: `--text-secondary` (#6B7280)
- Margin: `2.5rem` top/bottom
- Border radius: `0 0.5rem 0.5rem 0`

**Blockquote Content**:

- Paragraphs: `1rem` bottom margin
- Citations: `1rem` top margin, normal font style, `--text-muted` color
- Citation prefix: `"— "` (em dash)

**Nested Blockquotes**:

- Additional left/right margin: `1rem`
- Darker border color: `--ordio-blue-dark`
- Lighter background: `rgba(239, 246, 255, 0.5)`

### Tables

**Styling**:

- Width: `100%`
- Border collapse: `collapse`
- Margin: `2.5rem` top/bottom
- Border radius: `0.5rem`
- Overflow: `hidden`
- Box shadow: `var(--shadow-md)`

**Table Headers (th)**:

- Background: `var(--ordio-blue-light)`
- Padding: `1rem`
- Text align: `left`
- Font weight: `600`
- Color: `--text-primary`
- Border bottom: `2px solid var(--ordio-blue)`

**Table Cells (td)**:

- Padding: `0.875rem 1rem`
- Border bottom: `1px solid var(--border-color)`
- Color: `--text-primary`

**Table Rows**:

- Hover: `#F9FAFB` background
- Last row: No bottom border

**Responsive Tables**:

- Mobile font size: `0.875rem` (14px)
- Mobile padding: `0.75rem 0.5rem`
- Mobile margins: `2rem` top/bottom

## Links

### Link Styling

**Default State**:

- Color: `var(--ordio-blue)` (#4D8EF3)
- Text decoration: `underline`
- Underline thickness: `1.5px`
- Underline offset: `0.2em`
- Underline color: `rgba(77, 142, 243, 0.3)`
- Transition: `color 0.2s ease, text-decoration-color 0.2s ease`

**Hover State**:

- Color: `var(--ordio-blue-dark)` (#3B82F6)
- Underline color: `var(--ordio-blue-dark)`

**Focus State**:

- Outline: `2px solid var(--ordio-blue)`
- Outline offset: `2px`
- Border radius: `0.25rem`
- Text decoration: `none` (on focus)
- Text decoration: `underline` (on focus + hover)

**Links in Headings**:

- Color: `inherit`
- Text decoration: `none`
- Hover: Underline appears, color changes to `--ordio-blue`

## Responsive Design

### Mobile (< 640px)

**Typography Adjustments**:

- H1: `2rem` (32px)
- H2: `1.75rem` (28px)
- H3: `1.375rem` (22px)
- H4: `1.125rem` (18px)
- H5: `1rem` (16px)
- H6: `0.9375rem` (15px)

**Spacing Adjustments**:

- Paragraphs: `1.5rem` bottom margin
- Lists: `1.25rem` top/bottom margin, `1.5rem` left padding
- List items: `0.875rem` bottom margin, `0.375rem` left padding
- Blockquotes: `2rem` top/bottom margin, `1.25rem` left padding
- Code blocks: `2rem` top/bottom margin, `1.25rem` padding, `0.875rem` font size
- Inline code: `0.875rem` font size, `0.15rem 0.375rem` padding

### Tablet (640px - 1023px)

**Typography**:

- Medium heading sizes
- Balanced spacing
- Standard font sizes

### Desktop (≥ 1024px)

**Typography**:

- Full typography scale
- Optimal reading width: `700px` (43.75rem)
- Generous spacing
- Maximum readability

## Accessibility

### Focus States

**Interactive Elements**:

- Visible `2px` outline
- Ordio blue color
- `2px` offset for visibility
- Border radius for rounded appearance

### Reduced Motion

**Support**:

- Transitions disabled when `prefers-reduced-motion: reduce`
- No animation on links or interactive elements

### High Contrast

**Support**:

- Enhanced borders (`2px` instead of `1px`)
- Thicker underlines (`2px` instead of `1.5px`)
- Thicker blockquote borders (`6px` instead of `4px`)

### Print Styles

**Optimizations**:

- Font size: `12pt`
- Line height: `1.6`
- Page break controls for headings and block elements
- Links display URLs in parentheses
- Black text for better print contrast

## Brand Colors

### Text Colors

- **Primary**: `--text-primary` (#1F2937) - Main text, headings
- **Secondary**: `--text-secondary` (#6B7280) - Blockquotes, secondary text
- **Muted**: `--text-muted` (#9CA3AF) - Citations, small text

### Accent Colors

- **Ordio Blue**: `--ordio-blue` (#4D8EF3) - Links, accents, borders
- **Ordio Blue Dark**: `--ordio-blue-dark` (#3B82F6) - Hover states
- **Ordio Blue Light**: `--ordio-blue-light` (#EFF6FF) - Backgrounds, highlights

## Best Practices

### Typography Usage

1. **Heading Hierarchy**: Use headings in order (H2 → H3 → H4), don't skip levels
2. **Paragraph Length**: Keep paragraphs to 2-3 sentences for readability
3. **List Usage**: Use unordered lists for items without order, ordered lists for steps or rankings
4. **Emphasis**: Use strong/bold sparingly, don't overuse emphasis
5. **Code**: Use inline code for short snippets, code blocks for longer examples

### Spacing Guidelines

1. **Consistent Rhythm**: Maintain consistent spacing between elements
2. **First/Last Elements**: Reduce margins for first/last elements in containers
3. **After Headings**: Reduce top margin for content immediately after headings
4. **Nested Elements**: Reduce spacing for nested elements (lists, blockquotes)

### Accessibility Guidelines

1. **Color Contrast**: Ensure WCAG AA compliance (4.5:1 for normal text, 3:1 for large text)
2. **Focus Indicators**: Always provide visible focus states
3. **Text Size**: Minimum 16px for body text (18px used)
4. **Line Length**: Optimal 60-75 characters per line (700px reading width)

## CSS Variables Reference

```css
/* Typography Scale */
--blog-h1-size: 2.5rem; /* 40px */
--blog-h2-size: 2rem; /* 32px */
--blog-h3-size: 1.5rem; /* 24px */
--blog-h4-size: 1.25rem; /* 20px */
--blog-h5-size: 1.125rem; /* 18px */
--blog-h6-size: 1rem; /* 16px */

/* Spacing System */
--blog-spacing-xs: 0.5rem; /* 8px */
--blog-spacing-sm: 0.75rem; /* 12px */
--blog-spacing-md: 1rem; /* 16px */
--blog-spacing-lg: 1.5rem; /* 24px */
--blog-spacing-xl: 2rem; /* 32px */
--blog-spacing-2xl: 2.5rem; /* 40px */
--blog-spacing-3xl: 3rem; /* 48px */

/* Typography */
--blog-body-font-size: 1.125rem; /* 18px */
--blog-body-line-height: 1.75;
--blog-paragraph-spacing: 1.75rem; /* 28px */
```

## Related Documentation

- `docs/content/blog/BLOG_TEMPLATE_BEST_PRACTICES.md` - Best practices guide
- `docs/content/blog/EMBED_HANDLING_GUIDE.md` - Embedded content guide
- `.cursor/rules/blog-templates.mdc` - Cursor rules with typography patterns