This guide illustrates the correct margin specifications between code blocks and various content elements. Each example precisely demonstrates the pixel measurements needed to maintain proper visual hierarchy and readability.

This paragraph precedes a code block. When transitioning from paragraph text to a code block, we use a 24px margin. This provides enough separation to distinguish the code as a separate element while maintaining its connection to the paragraph that introduces or explains it.

javascript// Placeholder code block
function spacing() {
  const baseline = 8;
  const lineHeight = 30;
  
  // Margin calculations
  const elementMargin = baseline * 3;  // 24px
  const visualBreakMargin = baseline * 4;  // 32px
  const sectionBreakMargin = baseline * 5;  // 40px
  
  return {
    elementMargin,
    visualBreakMargin,
    sectionBreakMargin
  };
}

javascript// Placeholder code block
function spacing() {
  const baseline = 8;
  const lineHeight = 30;
  
  // Margin calculations
  const elementMargin = baseline * 3;  // 24px
  const visualBreakMargin = baseline * 4;  // 32px
  const sectionBreakMargin = baseline * 5;  // 40px
  
  return {
    elementMargin,
    visualBreakMargin,
    sectionBreakMargin
  };
}

This paragraph appears 24px below the code block above. When returning to regular paragraph text after a code block, we maintain the same 24px spacing to create symmetry in the document's vertical rhythm. This consistent approach makes the content more predictable and easier to read, especially in technical documentation where code and explanatory text frequently alternate.

javascript// Placeholder code block
function spacing() {
  const baseline = 8;
  const lineHeight = 30;
  
  // Margin calculations
  const elementMargin = baseline * 3;  // 24px
  const visualBreakMargin = baseline * 4;  // 32px
  const sectionBreakMargin = baseline * 5;  // 40px
  
  return {
    elementMargin,
    visualBreakMargin,
    sectionBreakMargin
  };
}

javascript// Placeholder code block
function spacing() {
  const baseline = 8;
  const lineHeight = 30;
  
  // Margin calculations
  const elementMargin = baseline * 3;  // 24px
  const visualBreakMargin = baseline * 4;  // 32px
  const sectionBreakMargin = baseline * 5;  // 40px
  
  return {
    elementMargin,
    visualBreakMargin,
    sectionBreakMargin
  };
}

The 40px spacing before a heading creates a clear section break, regardless of what content type precedes it. This consistent approach to section transitions improves content structure and readability, especially in technical documentation where code examples might conclude one section before moving to a new topic.

• This list precedes a code block

• When transitioning from a list to code

• We use a 24px margin

• This provides clear separation while maintaining context between the list and the code that follows

javascript// Placeholder code block
function spacing() {
  const baseline = 8;
  const lineHeight = 30;
  
  // Margin calculations
  const elementMargin = baseline * 3;  // 24px
  const visualBreakMargin = baseline * 4;  // 32px
  const sectionBreakMargin = baseline * 5;  // 40px
  
  return {
    elementMargin,
    visualBreakMargin,
    sectionBreakMargin
  };
}

javascript// Placeholder code block
function spacing() {
  const baseline = 8;
  const lineHeight = 30;
  
  // Margin calculations
  const elementMargin = baseline * 3;  // 24px
  const visualBreakMargin = baseline * 4;  // 32px
  const sectionBreakMargin = baseline * 5;  // 40px
  
  return {
    elementMargin,
    visualBreakMargin,
    sectionBreakMargin
  };
}

• This list appears 24px below the code block above

• The consistent 24px spacing maintains document rhythm

• While providing clear distinction between content types

• Often, this list might explain the code output or next steps

When multiple code blocks appear in sequence, proper spacing helps distinguish them as separate examples:

javascript// Placeholder code block
function spacing() {
  const baseline = 8;
  const lineHeight = 30;
  
  // Margin calculations
  const elementMargin = baseline * 3;  // 24px
  const visualBreakMargin = baseline * 4;  // 32px
  const sectionBreakMargin = baseline * 5;  // 40px
  
  return {
    elementMargin,
    visualBreakMargin,
    sectionBreakMargin
  };
}

javascript// Placeholder code block
function spacing() {
  const baseline = 8;
  const lineHeight = 30;
  
  // Margin calculations
  const elementMargin = baseline * 3;  // 24px
  const visualBreakMargin = baseline * 4;  // 32px
  const sectionBreakMargin = baseline * 5;  // 40px
  
  return {
    elementMargin,
    visualBreakMargin,
    sectionBreakMargin
  };
}

Notice the 24px spacing between consecutive code blocks. This creates enough separation to indicate these are distinct code examples while maintaining consistent document rhythm.

javascript// Placeholder code block
function spacing() {
  const baseline = 8;
  const lineHeight = 30;
  
  // Margin calculations
  const elementMargin = baseline * 3;  // 24px
  const visualBreakMargin = baseline * 4;  // 32px
  const sectionBreakMargin = baseline * 5;  // 40px
  
  return {
    elementMargin,
    visualBreakMargin,
    sectionBreakMargin
  };
}

javascript// Placeholder code block
function spacing() {
  const baseline = 8;
  const lineHeight = 30;
  
  // Margin calculations
  const elementMargin = baseline * 3;  // 24px
  const visualBreakMargin = baseline * 4;  // 32px
  const sectionBreakMargin = baseline * 5;  // 40px
  
  return {
    elementMargin,
    visualBreakMargin,
    sectionBreakMargin
  };
}

The 32px spacing between images and code blocks acknowledges the stronger visual break that images create in the content flow and provides room for the eye to transition between processing visual information and reading code.

javascript// Placeholder code block
function spacing() {
  const baseline = 8;
  const lineHeight = 30;
  
  // Margin calculations
  const elementMargin = baseline * 3;  // 24px
  const visualBreakMargin = baseline * 4;  // 32px
  const sectionBreakMargin = baseline * 5;  // 40px
  
  return {
    elementMargin,
    visualBreakMargin,
    sectionBreakMargin
  };
}

javascript// Placeholder code block
function spacing() {
  const baseline = 8;
  const lineHeight = 30;
  
  // Margin calculations
  const elementMargin = baseline * 3;  // 24px
  const visualBreakMargin = baseline * 4;  // 32px
  const sectionBreakMargin = baseline * 5;  // 40px
  
  return {
    elementMargin,
    visualBreakMargin,
    sectionBreakMargin
  };
}

javascript// Placeholder code block
function spacing() {
  const baseline = 8;
  const lineHeight = 30;
  
  // Margin calculations
  const elementMargin = baseline * 3;  // 24px
  const visualBreakMargin = baseline * 4;  // 32px
  const sectionBreakMargin = baseline * 5;  // 40px
  
  return {
    elementMargin,
    visualBreakMargin,
    sectionBreakMargin
  };
}

Paragraph on Warpcast

Warm up with a delicious spicy Italian chicken sausage and barley soup! This hearty recipe from @galazio combines sausage, fresh veggies, and a smooth, creamy texture thanks to a perfectly tempered egg. Perfect for cozy nights in your kitchen! Check out the full blog post for details. https://paragraph.com/@galazio/spicy-italian-chicken-sausage-and-barley-soup

Farcaster

Paragraph on Warpcast

Warm up with a delicious spicy Italian chicken sausage and barley soup! This hearty recipe from @galazio combines sausage, fresh veggies, and a smooth, creamy texture thanks to a perfectly tempered egg. Perfect for cozy nights in your kitchen! Check out the full blog post for details. https://paragraph.com/@galazio/spicy-italian-chicken-sausage-and-barley-soup

Farcaster

javascript// Placeholder code block
function spacing() {
  const baseline = 8;
  const lineHeight = 30;
  
  // Margin calculations
  const elementMargin = baseline * 3;  // 24px
  const visualBreakMargin = baseline * 4;  // 32px
  const sectionBreakMargin = baseline * 5;  // 40px
  
  return {
    elementMargin,
    visualBreakMargin,
    sectionBreakMargin
  };
}

javascript// Placeholder code block
function spacing() {
  const baseline = 8;
  const lineHeight = 30;
  
  // Margin calculations
  const elementMargin = baseline * 3;  // 24px
  const visualBreakMargin = baseline * 4;  // 32px
  const sectionBreakMargin = baseline * 5;  // 40px
  
  return {
    elementMargin,
    visualBreakMargin,
    sectionBreakMargin
  };
}

javascript// Placeholder code block
function spacing() {
  const baseline = 8;
  const lineHeight = 30;
  
  // Margin calculations
  const elementMargin = baseline * 3;  // 24px
  const visualBreakMargin = baseline * 4;  // 32px
  const sectionBreakMargin = baseline * 5;  // 40px
  
  return {
    elementMargin,
    visualBreakMargin,
    sectionBreakMargin
  };
}

Note the 40px spacing between the divider and the code block. Dividers signal significant breaks in content, so the larger margin helps establish a clear separation between sections.

This visual guide demonstrates all code block margin specifications within our typography system:

1. Text Elements to/from Code Block:

   • Paragraph to/from Code Block: 24px

   • List to/from Code Block: 24px

   • Code Block to Code Block: 24px

   • Heading to Code Block: 24px

2. Visual Elements to/from Code Block:

   • Image to/from Code Block: 32px

   • Table to/from Code Block: 32px

   • Embed to/from Code Block: 32px

3. Section Transitions:

   • Code Block to Heading: 40px

   • Divider to/from Code Block: 40px

These margin specifications create a coherent reading experience by establishing:

• Clear distinction between code and explanatory content

• Consistent vertical rhythm throughout technical documentation

• Appropriate visual separation based on content type

• Improved readability for technical material

Consistent application of these spacing guidelines helps readers navigate between code and explanatory content with ease, improving both comprehension and engagement.