tailwindcss-typography

Tailwind CSS Typography adds a set of prose classes that apply sensible, professionally designed typographic styles to raw HTML you don’t directly control — content rendered from Markdown, pulled from a CMS, or otherwise assembled outside your component templates. Rather than hand-writing CSS for every heading, list, blockquote, and code block a content pipeline might produce, you wrap the container in prose and get consistent spacing, font sizing, and color treatment out of the box.

The plugin ships five built-in gray-scale color themes, five type-scale sizes with responsive breakpoint support, a dark-mode prose-invert variant, and granular per-element modifiers (prose-headings:, prose-a:, prose-img:, etc.) for overriding individual tag styles without leaving your markup. It works with both Tailwind CSS v3’s config-based plugin API and v4’s @plugin CSS directive, and remains one of the most widely used official Tailwind plugins for blogs, docs sites, and any Markdown-driven content.

What You Get

• prose utility classes that apply typographic defaults to a block of unstyled HTML
• Five gray-scale color themes (gray, slate, zinc, neutral, stone) selectable via prose-<color> modifiers
• Five responsive type-scale sizes (prose-sm through prose-2xl) with hand-tuned spacing
• Built-in dark mode support via the prose-invert modifier
• Per-element modifiers (prose-headings:, prose-a:, prose-img:, etc.) for targeted overrides
• Support for custom color themes via the @utility directive (v4) or typography config (v3)

Common Use Cases

• Markdown-rendered blog posts - styling article bodies converted from Markdown into HTML without hand-writing CSS for every element
• Headless CMS content - applying consistent typography to rich-text fields pulled from a CMS where you don’t control the markup
• Documentation sites - giving docs pages built from MDX or static site generators readable, professional typography by default
• Rendered HTML fragments (emails, previews) - quickly styling arbitrary HTML blocks for legible presentation

Under The Hood

Architecture The plugin is a single entry point (src/index.js) built with tailwindcss/plugin.withOptions, wrapping a className/target options object into an addComponents/addVariant builder driven by a large declarative style config (src/styles.js, ~1,600 lines) that maps modifier names — DEFAULT, sm through 2xl, invert, and each gray-scale theme — to nested CSS-in-JS objects read from theme('typography'). Small pure helpers in src/utils.js (deep merge, pseudo-element normalization via postcss-selector-parser) are consumed by index.js’s inWhere/configToCss functions, which translate the style config into :where()-wrapped selectors scoped against a not-<className> escape hatch. There’s no runtime state — it’s a single-pass config-to-CSS compiler invoked once at Tailwind build time, so changes to configToCss/inWhere ripple through every generated prose-* utility since all size and color variants funnel through the same code path.

Tech Stack Plain CommonJS JavaScript (no TypeScript source, though a hand-written src/index.d.ts ships for consumers), with tailwindcss as a peer dependency (>=3.0.0 || >=4.0.0 || insiders) and postcss-selector-parser (pinned 6.0.10) as the only runtime dependency. Dev tooling includes Jest 29 for tests, a Next.js 12 + MDX demo site (demo/) for local preview, Prettier for formatting, and Tailwind/PostCSS/autoprefixer to build that demo. The published package ships raw src/*.js files directly (per the files field in package.json) with no bundling step for the library itself.

Code Quality Tests live in src/index.test.js (~1,400 lines) and assert on actual compiled CSS output using real Tailwind + PostCSS compilation, backed by a custom Jest matcher (toMatchCss in jest/customMatchers.js) that strips whitespace before comparing. CI (.github/workflows/nodejs.yml) runs the full test suite on every push and PR across two Node versions. Naming is clear and consistent, error handling is minimal by design since the plugin performs a pure config-to-CSS transform with no I/O, and Prettier config in package.json enforces consistent style across the small codebase.

What Makes It Unique Rather than exposing typography as ad hoc utility classes, the plugin generates entire hand-designed style systems (five sizes × six color themes × light/dark) as a single composable prose primitive, using :where() selector wrapping so consumer Tailwind utilities always win on specificity without needing !important. Its per-element modifier syntax (prose-a:, prose-headings:) extends Tailwind’s own modifier system to reach into typography defaults directly from markup — a pattern few other CSS typography resets offer.