Blog & Article Design

Overview

Professional design system for blog posts, articles, and long-form content pages. Based on patterns from Stripe, Vercel, Tailwind, and Linear documentation. Provides specific typography scales, spacing rules, code block styling, and visual hierarchy guidelines optimized for readability on both dark and light themes.

Instructions

When designing or improving a blog/article page, follow these steps in order.

Step 1: Set the content container

The single most important decision is content width. Optimal reading length is 60-70 characters per line.

Container width: max-w-2xl (672px) for prose-heavy articles
                 max-w-3xl (768px) if content includes wide code blocks or tables
Centering:       mx-auto
Horizontal pad:  px-6 (24px on each side)
Top padding:     pt-24 (96px) to clear fixed headers
Bottom padding:  pb-16 (64px)

Never use

max-w-4xl

or wider for article text — lines become too long to read comfortably.

Step 2: Define the typography scale

Use a constrained type scale with clear hierarchy. Every level must be visually distinct.

Dark theme (zinc palette):

H1:     text-3xl md:text-4xl font-bold text-zinc-50          — Page title, one per page
H2:     text-2xl font-semibold tracking-tight text-zinc-50   — Major sections, mt-12 mb-4
H3:     text-xl font-semibold tracking-tight text-zinc-50    — Subsections, mt-8 mb-3
H4:     text-lg font-semibold text-zinc-100                  — Minor headings, mt-6 mb-2
Body:   text-base leading-7 text-zinc-300 mb-6               — Paragraphs, 16px/28px
Strong: text-zinc-50 font-semibold                           — Emphasis within body
Muted:  text-zinc-400                                        — Captions, metadata
Link:   text-accent underline decoration-accent/40           — Visible, accessible links

Light theme (gray palette):

H1:     text-3xl md:text-4xl font-bold text-gray-900
H2:     text-2xl font-semibold tracking-tight text-gray-900
H3:     text-xl font-semibold tracking-tight text-gray-900
Body:   text-base leading-7 text-gray-600 mb-6
Strong: text-gray-900 font-semibold
Muted:  text-gray-500

Key rules:

• Body line-height must be

  leading-7

  (1.75) for comfortable reading
• Paragraph spacing

  mb-6

  creates clear separation without feeling sparse
• Headings use

  tracking-tight

  for a polished, dense feel
• H2 gets

  mt-12

  — generous top margin signals a new major section

Step 3: Style lists and inline elements

Unordered: list-disc list-outside pl-6 space-y-2 text-zinc-300 my-6
Ordered:   list-decimal list-outside pl-6 space-y-2 text-zinc-300 my-6
List item: text-base leading-7
Inline code: bg-white/10 px-1.5 py-0.5 rounded-md text-[0.9em] font-mono text-zinc-200
Blockquote: border-l-4 border-zinc-700 pl-4 my-6 text-zinc-400 italic
Horizontal rule: border-white/10 my-12

For ordered lists interrupted by other elements (code blocks), preserve the

start

attribute to maintain correct numbering.

Step 4: Design code blocks

Two distinct code block types:

Language-tagged blocks (syntax-highlighted code):

Container: my-6 rounded-xl border border-white/10 bg-zinc-900 overflow-hidden
Header:    flex items-center gap-2 px-4 py-2.5 border-b border-white/5 bg-zinc-900/80
Lang label: text-xs font-mono text-zinc-500
Code area: px-5 py-4 overflow-x-auto
Pre:       text-sm leading-relaxed whitespace-pre-wrap break-words

Text/output blocks (untagged or

text

language):

Container: my-6 rounded-xl border border-white/10 bg-zinc-900 overflow-x-auto
Pre:       px-5 py-4 text-sm leading-relaxed whitespace-pre-wrap break-words font-mono

For output blocks, apply line-by-line visual hierarchy:

• First non-empty line →

  text-zinc-50 font-semibold

  (title)
• ALL CAPS lines →

  text-zinc-100 font-medium

  (section header)
• Lines ending with

  :

  (under 60 chars) → section header style
• Numbered items (

  1. ...

  ) →

  text-zinc-200

• Divider lines (

  ---

  ,

  ===

  ) →

  text-zinc-700

• Dollar amounts, percentages →

  text-emerald-400

  highlight
• Everything else →

  text-zinc-400

  (body)
• Blank lines →

  h-3

  spacer

Step 5: Design tables

Wrapper:  overflow-x-auto my-6 rounded-xl border border-white/10
Table:    w-full text-sm border-collapse
Thead:    bg-zinc-900/50
Th:       text-left py-3 px-4 text-zinc-200 font-semibold text-xs uppercase tracking-wider
Tr:       border-b border-white/5
Td:       py-3 px-4 text-zinc-300

Step 6: Add page-level structure

A well-structured article page has these sections in order:

1. Breadcrumb — text-sm text-muted, links with hover:text-white
2. Title — H1, single line preferred, bold
3. Metadata bar — category badge, tags, author, date (flex-wrap gap-3)
4. Related resources — linked cards (if applicable)
5. Article body — markdown-rendered content
6. Footer — related articles, share buttons (optional)

Category badge style:

text-xs bg-accent/20 text-accent px-2 py-1 rounded capitalize

Tags:

text-xs text-muted

with

#

prefix

Step 7: Responsive behavior

Mobile (<640px):  px-6, text-3xl title, full-width code blocks
Tablet (640px+):  Same as mobile but wider line length
Desktop (768px+): text-4xl title, centered container

Code blocks should use

overflow-x-auto

on mobile and

whitespace-pre-wrap break-words

to avoid horizontal scroll when possible.

Examples

Example 1: React markdown component overrides for a dark-theme article

User request: "Create custom markdown components for my blog's article pages with a dark theme"

Implementation:

import React from 'react'

export const markdownComponents = {
  h1: () => null, // Title rendered separately above the article
  h2: ({ children }: any) => (
    <h2 className="text-2xl font-semibold tracking-tight text-zinc-50 mt-12 mb-4">{children}</h2>
  ),
  h3: ({ children }: any) => (
    <h3 className="text-xl font-semibold tracking-tight text-zinc-50 mt-8 mb-3">{children}</h3>
  ),
  p: ({ children }: any) => (
    <p className="text-base leading-7 text-zinc-300 mb-6">{children}</p>
  ),
  strong: ({ children }: any) => (
    <strong className="text-zinc-50 font-semibold">{children}</strong>
  ),
  a: ({ href, children }: any) => (
    <a href={href} className="text-emerald-400 underline decoration-emerald-400/40 underline-offset-2 hover:decoration-emerald-400 transition-colors" target="_blank" rel="noopener noreferrer">{children}</a>
  ),
  ul: ({ children }: any) => (
    <ul className="list-disc list-outside pl-6 space-y-2 text-zinc-300 my-6">{children}</ul>
  ),
  ol: ({ children, start }: any) => (
    <ol start={start} className="list-decimal list-outside pl-6 space-y-2 text-zinc-300 my-6">{children}</ol>
  ),
  li: ({ children }: any) => (
    <li className="text-base leading-7 [&>p]:mb-0">{children}</li>
  ),
  code: ({ className, children }: any) => {
    if (className?.includes('language-')) return <code className={className}>{children}</code>
    return <code className="bg-white/10 px-1.5 py-0.5 rounded-md text-[0.9em] font-mono text-zinc-200">{children}</code>
  },
  pre: ({ children }: any) => (
    <div className="my-6 rounded-xl border border-white/10 bg-zinc-900 overflow-x-auto">
      <pre className="px-5 py-4 text-sm leading-relaxed whitespace-pre-wrap break-words">{children}</pre>
    </div>
  ),
  table: ({ children }: any) => (
    <div className="overflow-x-auto my-6 rounded-xl border border-white/10">
      <table className="w-full text-sm border-collapse">{children}</table>
    </div>
  ),
  blockquote: ({ children }: any) => (
    <blockquote className="border-l-4 border-zinc-700 pl-4 my-6 text-zinc-400 italic [&>p]:mb-0">{children}</blockquote>
  ),
}

Example 2: Article page layout with breadcrumbs and metadata

User request: "Build a use-case article page with a breadcrumb, title, category badge, and markdown body"

Implementation:

export default function ArticlePage({ article }) {
  return (
    <main className="pt-24 pb-16">
      <div className="max-w-2xl mx-auto px-6">
        {/* Breadcrumb */}
        <div className="flex items-center gap-2 text-sm text-zinc-500 mb-8">
          <a href="/articles" className="hover:text-white transition-colors">Articles</a>
          <span>/</span>
          <span className="text-white">{article.title}</span>
        </div>

        {/* Title */}
        <h1 className="text-3xl md:text-4xl font-bold text-zinc-50 mb-4">
          {article.title}
        </h1>

        {/* Metadata */}
        <div className="flex flex-wrap items-center gap-3 mb-8">
          <span className="text-xs bg-emerald-500/20 text-emerald-400 px-2 py-1 rounded capitalize">
            {article.category}
          </span>
          {article.tags.map(tag => (
            <span key={tag} className="text-xs text-zinc-500">#{tag}</span>
          ))}
        </div>

        {/* Article body */}
        <article>
          <ReactMarkdown components={markdownComponents}>
            {article.body}
          </ReactMarkdown>
        </article>
      </div>
    </main>
  )
}

Guidelines

• 65-70 characters per line is the optimal reading width.

  max-w-2xl

  achieves this at 16px body text. Never go wider for prose.
• Vertical rhythm matters. Consistent

  mb-6

  on paragraphs and

  my-6

  on blocks creates a predictable reading pace. Headings break the rhythm intentionally with larger top margins.
• Code blocks are visual anchors. They should stand out from prose with distinct borders and background. The

  rounded-xl border border-white/10 bg-zinc-900

  pattern creates a clean, contained look.
• Do not over-style output blocks. Simple monospace with subtle hierarchy (title bold, sections medium, body regular) is more readable than heavy formatting.
• Tables need horizontal overflow. Always wrap in

  overflow-x-auto

  to handle narrow viewports.
• Links must be visually distinct. Use both color and underline — color alone fails for colorblind users. The

  underline-offset-2

  with partial-opacity decoration is clean.
• Suppress the H1 in markdown rendering when the page title is already displayed above the article body. Duplicate titles look broken.
• Test with real content. Placeholder text hides spacing issues that only appear with actual paragraphs, lists, and code blocks.
• Dark theme contrast: body text at

  zinc-300

  (#d4d4d8) on

  #09090b

  background gives ~11:1 contrast ratio. Headings at

  zinc-50

  (#fafafa) give ~18:1. Both well above WCAG AA.