Chapter 7: Preflight

Core Idea

Preflight is Tailwind's opinionated base-style reset (built on modern-normalize), auto-injected into the base CSS layer, that strips browser defaults (margins, borders, list styles, heading sizes) so every element starts from a predictable, unstyled baseline that utilities then build on top of.

Key Concepts

• Auto-injected via layers: @import "tailwindcss" expands to three layered imports — tailwindcss/theme.css (layer theme), tailwindcss/preflight.css (layer base), tailwindcss/utilities.css (layer utilities) — Preflight is the middle one.
• All margins removed: every element (including headings, paragraphs, blockquotes) gets margin: 0 so nothing sneaks in outside your spacing scale.
• Borders reset to 0 solid + border-box: makes the bare border utility (which only sets border-width) always produce a visible 1px solid currentColor border; can surprise third-party widgets (e.g. Google Maps) that rely on default borders — fix locally with a scoped override in @layer base.
• Headings unstyled: h1-h6 inherit font-size/font-weight from their parent instead of using browser defaults, so heading styling is always deliberate and never accidentally deviates from your type scale.
• Lists unstyled: ol/ul/menu get list-style: none (no bullets/numbers) — restyle with list-style-type/list-style-position utilities. Accessibility note: unstyled lists aren't announced as lists by VoiceOver — add role="list" if the content is semantically a list you want to keep visually unstyled.
• Media elements are block-level: img, svg, video, canvas, audio, iframe, embed, object default to display: block; vertical-align: middle (avoids inline-element alignment gaps) — use the inline utility to opt back into inline behavior.
• Images/videos constrained: max-width: 100%; height: auto makes them responsive and non-overflowing by default — override with max-w-none when you need intrinsic sizing.
• [hidden] stays hidden: display: none !important on [hidden] (except hidden="until-found") so utility classes can't accidentally override the native hidden state.
• Extending vs. disabling: add your own base defaults via @layer base { h1 { ... } } (composes with Preflight); or disable Preflight entirely by importing theme.css and utilities.css directly without preflight.css, useful when integrating Tailwind into an existing project with its own base styles.
• Modular import options: when importing Tailwind's pieces individually (skipping the single @import "tailwindcss"), per-layer options move to their matching import — source(...) and important go on the utilities.css import, theme(static)/theme(inline) go on the theme.css import, and prefix(tw) must be added to both.

Code Examples

/* Disable Preflight while keeping theme + utilities */
@layer theme, base, components, utilities;
@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/utilities.css" layer(utilities);

/* Extend Preflight with your own base defaults */
@layer base {
  h1 { font-size: var(--text-2xl); }
  a  { color: var(--color-blue-600); text-decoration-line: underline; }
}

• What it demonstrates: opting out of Preflight for an existing-project migration, and the supported pattern for adding project-wide base styles on top of it.

Key Takeaways

1. Preflight resets are the reason border "just works" as a 1px solid border and headings need explicit utility classes to look like headings — both are deliberate, not bugs.
2. When a third-party component looks broken after adding Tailwind, check Preflight's border/margin resets first — scope a fix with @layer base rather than fighting specificity.
3. Disabling Preflight is a supported, common integration path — do it by omitting its import, not by trying to override every reset rule individually.

Connects To

• Adding Custom Styles: @layer base is the mechanism for both extending and locally overriding Preflight.
• Functions and Directives: the layer()/source()/theme()/prefix() import qualifiers used when disabling Preflight or customizing modular imports.