Next.js Academic Article (Distill-Inspired)

Create publication-quality academic articles with Distill.pub-inspired design using Next.js, React components, and modern web technologies.

When to Use This Skill

Trigger patterns:

"Create an academic paper/article/research document"

"I need a scientific publication with citations"

"Make a paper with margin notes and references"

"Build a research article like Distill.pub"

"Create an article with proper academic formatting"

Use this skill for:

Research papers and scientific publications

Technical articles with citations and references

Educational content requiring footnotes and sidenotes

Documentation with cross-references

Any content needing academic formatting with modern web features

Core Philosophy

Registry-First, Component-Based Design:

Content over layout - focus on substance first
Clean, minimal aesthetics - no unnecessary decoration
Proper spacing - generous whitespace for breathing room
Typography-first - readable serif body with sans-serif UI
Responsive by default - mobile to desktop adaptation

Key Features

Reading Progress Bar - Slim top bar tracking scroll position

Sticky Table of Contents - Auto-highlighting active section

Enhanced Citations - Hover previews with full bibliography

Sidenotes/Margin Notes - Desktop float, mobile inline

Hover Tooltips - Inline term definitions

Numbered Figures - Card-based with fade-in animation

Proper Spacing - Balanced layout without excessive whitespace

Academic Typography - Georgia/serif body, Inter/sans UI

Responsive Grid - Content + margin layout (collapses on mobile)

CRITICAL: Design System

Layout Dimensions

hljs css

--article-max: 700px;        /* Main content width */
--margin-col: 220px;         /* Sidebar/TOC width */
--gap-col: 3rem;            /* Grid gap */
max-width: 1200px;          /* Total grid max */

Spacing Rules

Footer spacing: mt-24 xl:mt-32 (96-128px) - NOT excessive

Section spacing: mb-16 between major sections

Paragraph spacing: my-5 (1.25rem)

TOC position: top-32 xl:top-40 (128px-160px from top)

Typography Scale

hljs css

- Body: Georgia, 'Times New Roman', serif (line-height: 1.8)
- UI/Headings: Inter, system-ui, sans-serif
- h2: 1.875rem (30px), font-weight: 700
- h3: 1.5rem (24px), font-weight: 600
- Body: 1rem (16px), line-height: 1.8

Color Palette

hljs css

- Links: text-blue-600 hover:text-blue-800
- Accents: sky-600 (progress bar, TOC active)
- Text: zinc-800 (body), zinc-900 (headings)
- Borders: zinc-200 (subtle separation)
- Background: white (main), zinc-50 (header/footer)

Quick Start

1. Project Setup

If starting fresh:

hljs bash

# Assume Next.js project already exists
# Install shadcn/ui components
npx shadcn@latest add card badge hover-card

2. Create Component Structure

Create these components in /components/article/:

components/article/
├── ArticleHeader.tsx       # Header with title, author, abstract
├── Citation.tsx            # Inline citations with hover
├── Figure.tsx              # Enhanced figure with animations
├── ReadingProgress.tsx     # Progress bar
├── References.tsx          # Bibliography section
├── Sidenote.tsx           # Margin notes
├── TableOfContents.tsx    # Sticky TOC with active tracking
├── Tooltip.tsx            # Inline term definitions
└── index.ts               # Export all components

3. Add Global Styles

Add to app/globals.css:

hljs css

:root {
  --article-max: 700px;
  --margin-col: 220px;
  --gap-col: 3rem;
  --font-body: 'Georgia', 'Times New Roman', serif;
  --font-ui: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
}

.article-grid {
  display: grid;
  grid-template-columns: minmax(0, 1fr);
  gap: var(--gap-col);
}

@media (min-width: 1280px) {
  .article-grid {
    grid-template-columns: var(--article-max) var(--margin-col);
    align-items: start;
    justify-content: center;
    max-width: 1200px;
    margin: 0 auto;
  }
}

.article-prose {
  font-variant-ligatures: common-ligatures;
  font-feature-settings: "liga" 1, "kern" 1;
  text-wrap: pretty;
  font-family: var(--font-body);
  line-height: 1.8;
  color: theme('colors.zinc.800');
}

4. Create Article Page Template

hljs tsx

// app/articles/[slug]/page.tsx
import {
  ArticleHeader,
  ReadingProgress,
  TableOfContents,
  Figure,
  Citation,
  References,
  Sidenote,
  Tooltip,
} from '@/components/article';
import type { Reference, TocItem } from '@/components/article';

export default async function ArticlePage() {
  const tocItems: TocItem[] = [
    { id: 'introduction', title: 'Introduction', level: 2 },
    { id: 'methods', title: 'Methods', level: 2 },
    { id: 'results', title: 'Results', level: 2 },
  ];

  const references: Reference[] = [
    {
      id: 'smith2023',
      number: 1,
      authors: 'Smith, J. & Doe, M.',
      year: '2023',
      title: 'Understanding Research Methods',
      publication: 'Journal of Science',
      volume: '45(3)',
      pages: '123-145',
      doi: '10.1234/example',
    },
  ];

  return (
    <div className="min-h-screen bg-white">
      <ReadingProgress />

      <ArticleHeader
        title="Your Article Title"
        subtitle="A comprehensive study of..."
        authors={[
          {
            name: 'Author Name',
            url: 'https://example.com',
          },
        ]}
        date="2025"
        abstract="This article explores..."
        keywords={['keyword1', 'keyword2']}
        projectName="Research Project"
        projectDescription="Based on XYZ Data"
      />

      <div className="max-w-7xl mx-auto px-6 py-12 xl:px-8">
        <div className="article-grid">
          <main>
            <article className="article-prose">
              <section id="introduction" className="mb-16 scroll-mt-24">
                <h2>Introduction</h2>
                <p>
                  Your content with{' '}
                  <Citation
                    id="smith2023"
                    number={1}
                    authors="Smith & Doe"
                    year="2023"
                    title="Understanding Research Methods"
                  />{' '}
                  and{' '}
                  <Tooltip
                    term="Technical Term"
                    definition="A clear explanation of this term."
                  >
                    hover terms
                  </Tooltip>.
                </p>

                <Sidenote number={1} type="note">
                  A helpful margin note providing additional context.
                </Sidenote>
              </section>

              <Figure
                id="fig-1"
                number={1}
                title="Figure Title"
                caption="Description of what the figure shows..."
              >
                <img src="/image.png" alt="Description" className="w-full" />
              </Figure>

              <References references={references} />
            </article>
          </main>

          <TableOfContents items={tocItems} />
        </div>
      </div>

      <footer className="border-t border-zinc-200 bg-zinc-50 mt-24 xl:mt-32">
        <div className="max-w-7xl mx-auto px-6 py-12 text-center">
          <div className="space-y-3 text-sm text-zinc-600">
            <p className="font-medium text-zinc-700">
              Project Name • Project Description
            </p>
            <p>
              © 2025 Author •{' '}
              <a href="https://example.com" className="text-blue-600 hover:underline">
                example.com
              </a>
            </p>
            <p className="italic text-zinc-500 max-w-3xl mx-auto">
              Additional attribution or project description.
            </p>
          </div>
        </div>
      </footer>
    </div>
  );
}

Component API

ArticleHeader

hljs tsx

<ArticleHeader
  title="Article Title"
  subtitle="Subtitle text"
  authors={[{ name: 'Name', url: 'https://...' }]}
  date="2025"
  abstract="Abstract text..."
  keywords={['tag1', 'tag2']}
  projectName="Project Name"
  projectDescription="Description"
/>

Design specs:

White background (bg-white) - NO gray background

Multi-line author format with project attribution

Abstract has blue left border (border-l-4 border-blue-600)

Keywords hidden by default

Responsive typography

Citation

hljs tsx

<Citation
  id="ref-id"
  number={1}
  authors="Smith & Doe"
  year="2023"
  title="Paper Title"
/>

Features:

Numbered format: [1]

Hover preview with details

Links to References section

Blue color scheme

Figure

hljs tsx

<Figure
  id="fig-1"
  number={1}
  title="Figure Title"
  caption="Caption text..."
  wide={false}
>
  <img src="..." alt="..." />
</Figure>

Design specs:

Card-based with rounded corners (rounded-2xl)

Subtle shadow and border

Fade-in animation on scroll

Optional wide prop for larger figures

Blue accent for figure numbers

Sidenote

hljs tsx

<Sidenote number={1} type="note">
  Margin content...
</Sidenote>

Types:

note - general notes

definition - term definitions

example - examples

Behavior:

Desktop: floats in right margin

Mobile: inline card

hljs tsx

<Tooltip term="Term" definition="Definition text">
  hover text
</Tooltip>

Features:

Dotted underline indicator

Hover card with definition

200ms delay for better UX

References

hljs tsx

const refs: Reference[] = [
  {
    id: 'ref-id',
    number: 1,
    authors: 'Authors',
    year: '2023',
    title: 'Title',
    publication: 'Journal',
    doi: '10.1234/example',
  },
];

<References references={refs} />

Features:

Standard academic citation format

Numbered with anchor IDs

DOI and URL support

Clickable links

CRITICAL PATTERNS

❌ DO NOT:

Use mt-40 or mt-56 for footer - TOO MUCH SPACE
Use gray background for header - should be white
Use thick blue borders for appendix sections - minimal styling only
Make TOC wider than 220px - causes excessive right spacing
Use bg-sky-50 backgrounds excessively - looks clunky

✅ DO:

Use mt-24 xl:mt-32 for footer spacing
Use white background for header (bg-white)
Use minimal borders (border-l-2 border-zinc-300) for appendix
Keep article grid under 1200px total width
Use generous line-height (1.8) for body text

Content Structure

hljs tsx

<section id="unique-id" className="mb-16 scroll-mt-24">
  <h2 className="group">
    Section Title
    <a href="#unique-id" className="ml-2 text-zinc-400 opacity-0 group-hover:opacity-100">
      #
    </a>
  </h2>

  <div className="relative">
    <p>Paragraph content...</p>
    <Sidenote number={1}>Note content</Sidenote>
  </div>
</section>

Data/Methods Appendix Styling

For structured data sections (like "Data Source", "Sample", etc.):

hljs tsx

<div className="mb-8 space-y-3">
  {Object.entries(data).map(([key, value]) => (
    <div key={key} className="pl-6 border-l-2 border-zinc-300">
      <h4 className="font-semibold text-zinc-800 mb-1.5 text-sm uppercase tracking-wide">
        {key.replace(/_/g, ' ')}
      </h4>
      <p className="text-base text-zinc-700 leading-relaxed">
        {value}
      </p>
    </div>
  ))}
</div>

Workflow

Typical Implementation

Create page structure with ArticleHeader, ReadingProgress, TOC
Add article grid with main content and sidebar
Write content using sections with proper IDs
Add citations with Citation component and References section
Include figures with Figure component
Add sidenotes for supplementary information
Add tooltips for term definitions
Style footer with project attribution
Test responsive behavior on mobile

Best Practices

Always wrap related paragraph + sidenote in <div className="relative">

Use unique IDs for all sections (lowercase, hyphenated)

Reference figures before they appear in text

Keep paragraphs under 90 words

Use serif for body, sans-serif for UI

Test on mobile - ensure sidenotes display correctly

Troubleshooting

TOC not highlighting

Solution: Ensure sections have id attribute and scroll-mt-24 class

Sidenotes overlapping

Solution: Wrap each paragraph + sidenote in <div className="relative"> container

Excessive right-side spacing

Solution: Check article grid max-width (should be 1200px) and margin-col (should be 220px)

Footer too spaced out

Solution: Use mt-24 xl:mt-32 NOT mt-40 or higher

Version

Version: 2.0.0 Compatible With: Next.js 14+, React 18+, TypeScript 5+ Updated: October 2025

nextjs-academic-article

Next.js Academic Article (Distill-Inspired)

When to Use This Skill

Core Philosophy

Key Features

CRITICAL: Design System

Layout Dimensions

Spacing Rules

Typography Scale

Color Palette

Quick Start

1. Project Setup

2. Create Component Structure

3. Add Global Styles

4. Create Article Page Template

Component API

ArticleHeader

Citation

Figure

Sidenote

Tooltip

TableOfContents

References

CRITICAL PATTERNS

❌ DO NOT:

✅ DO:

Content Structure

Data/Methods Appendix Styling

Workflow

Typical Implementation

Best Practices

Troubleshooting

TOC not highlighting

Sidenotes overlapping

Excessive right-side spacing

Footer too spaced out

Version

Related Categories