user-agent-base

user-agent-base is a portable reset and base layer for web projects. It gives you a neutral starting point for typography, spacing, media, forms, tables, and semantic HTML, while exposing most of its styling through CSS custom properties. The reset is part of the baseline and should always be loaded with the package.

What you get

• A small reset layer for predictable element defaults.
• A modular base layer grouped by HTML families.
• A single documented entrypoint that includes both reset and base styles.
• Published CSS artifacts for projects that want to consume plain CSS.

Install

npm install user-agent-base

Entry points

SCSS

Use the package root when you want the full baseline, including the reset:

@use 'user-agent-base';

CSS

Use the published CSS file when your stack does not compile Sass:

@import 'user-agent-base/main.css';

Design approach

The base layer is organized by families of HTML elements rather than by visual components. That makes it easier to reason about what each module changes and to override only the area you need.

The main source of customization is CSS variables defined in the base entrypoint. You can override them in your own stylesheet:

:root {
  --body-font-family: system-ui, sans-serif;
  --body-color: #222;
  --heading-font-family: Georgia, serif;
  --link-color: #0b57d0;
  --code-bg-color: rgba(0, 0, 0, 0.06);
}

Module families

Structure

Applies defaults to html, body, and common semantic wrappers such as main, header, footer, section, article, aside, and nav.

Use this when you want a consistent page shell with predictable margins, typography, and body colors.

Headings

Normalizes h1 to h6 and heading groups.

Use this for article pages, documentation, or any content site where heading scale and spacing matter.

Content flow

Handles p, blockquote, and hr.

Use this for editorial content where paragraph rhythm and separators should stay consistent.

Anchors

Handles a and explicit link-state pseudo-classes.

The link state order follows LVHA (:link, :visited, :hover, :active) to keep state precedence predictable.

Use this when you want a stable default for link states while keeping color and decoration tokens easy to override.

Inline content

Handles emphasis, metadata text, marks, subscript and superscript, bidirectional text, and ruby annotations.

Use this for long-form content that mixes prose, inline references, abbreviations, citations, and language-specific annotations.

Code

Styles code, kbd, samp, tt, and pre with monospace typography and compact block presentation.

Use this for docs, technical articles, changelogs, and API examples.

Forms

Covers form controls, fieldsets, labels, focus states, disabled states, and common input types.

Use this when you need a clean baseline for login forms, filters, contact forms, or admin interfaces.

Interactive

Styles disclosure and dialog-related elements such as details, summary, dialog, and noscript.

Use this for accordions, progressive disclosure panels, and simple modal patterns.

Lists

Normalizes ordered and unordered lists, menu lists, and description lists.

Use this for navigation, outlines, feature lists, glossaries, and definition content.

Media

Covers responsive media and embedded content such as img, video, picture, svg, iframe, object, audio, and figures.

Use this for galleries, embeds, responsive illustrations, and captioned media.

Tables

Styles table structure, headers, captions, rows, and cells.

Use this for data tables, pricing tables, and comparison matrices.

Accessibility

Includes accessibility-oriented defaults such as reduced-motion handling.

Use this as a lightweight foundation before layering on your own interactions and transitions.

Unstylable coverage

Tracks non-rendered or non-stylable elements so the base layer stays complete and easy to audit.

Use this mainly as a maintenance and coverage aid; it is not intended to affect visible layout.

Recommended usage scenarios

Blog or documentation site

Import the package root and override the typography tokens first. This gives you a stable foundation for headings, paragraphs, lists, code, and tables.

Application shell

Import the package root, then only override the variables for body, forms, and links. This keeps the UI neutral without forcing a design system.

Plain CSS integration

If your project does not use Sass, import the compiled CSS file directly and override the CSS variables after the import.

Advanced customization

The source tree keeps the reset and base layers separated internally so the package can be maintained cleanly, but the documented public contract is the combined baseline.

Project structure

• index.scss: Package-level SCSS entrypoint.
• src/base/: Base families organized by HTML function.
• src/reset/: Reset-only layer.
• dist/: Generated CSS artifacts published with the package.

License

ISC