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:

tsx
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:

tsx
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.