Skip to main content GitHub corner

Acorn CSS

A lightweight, classless CSS baseline that styles semantic HTML out of the box. The stylesheet you start with — not the one you build everything with.

# Getting Started

Acorn makes every native HTML element look good from the first line — the stuff that's easy to forget until launch day: blockquotes, tables, figures, footnotes, form controls. Around 5KB gzipped, no JavaScript required.

# Installation

Via npm

Install the package from npm:

npm install acorn.css

Then import it:

import 'acorn.css';

Or in CSS:

@import 'acorn.css';

Via CDN

<link rel="stylesheet" href="https://unpkg.com/acorn.css@latest/dist/acorn.min.css">

Quick start — customize with CSS variables

:root {
  --primary: #0b779f;     /* cyan */
  --secondary: #f4bb1a;   /* gold */
  --accent: #e62e6b;      /* magenta / pink */
  --button-radius: 1.5625rem;
  --container-default: 60rem;
}

# What Acorn is (and isn't)

Acorn styles content, not layout. It's opinionated about how content looks and reads, and deliberately not a grid system, a utility framework, or a component library. It ships no presentational classes — so when you reach for a class, it's yours and you know exactly what it does.

  • Classless: write semantic HTML, get a styled page.
  • Complete: styles the elements people forget — blockquotes, tables, figures, footnotes, task lists, form controls.
  • Customizable: everything themes through CSS custom properties.
  • Accessible: WCAG AA color contrast and proper focus management out of the box.
  • Tiny: around 5KB gzipped, no JavaScript.

Because it's classless, anything that emits clean semantic HTML — including Markdown and AI-generated content — gets styled automatically.

# Customization

Customize through CSS custom properties:

--primary, --secondary, --accent
CMYK-leaning brand colors (cyan, gold, magenta) with -light/-dark variants. All defaults pass WCAG AA in both themes.
--space-1 through --space-5
Spacing scale, rule of 2: 8px, 16px, 32px, 64px, 128px. Deliberately coarse — fine spacing is your layout's job.
--text-xs through --text-3xl
Type scale (1.25 ratio). Display sizes scale fluidly with the viewport via clamp(); body text stays fixed.
--container-narrow, --container-default
Reading widths: 45rem (narrow) and 60rem (default).
--border-radius
Base radius for inputs, code, cards.
--button-radius
Button radius, separate from --border-radius so buttons round independently (25px default).

Dark mode

Built in. Toggle it with an attribute:

<html data-theme="dark"> <!-- or "light" -->

Or follow the system preference with a line of JavaScript:

const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
document.documentElement.setAttribute('data-theme', prefersDark ? 'dark' : 'light');

Note: this demo uses the toggle button in the bottom-right corner.

# Typography

Every heading and text element styled automatically, on a fluid type scale.

# Heading Hierarchy

Heading 1 — Main Title

Heading 2 — Section Title

Heading 3 — Subsection

Heading 4 — Article Title

Heading 5 — Subheading
Heading 6 — Minor Heading

# Inline Text Elements

This is a paragraph with bold text, italic text, and a link. The baseline provides consistent spacing and typography that scales across devices.

You can use inline code, Cmd + C keyboard shortcuts, highlighted text, small text, and superscript / subscript.

Additional semantic elements: HTML, definition terms, variables, , and inline quotations.

# Lists and Definitions

  • Automatic styling for list items
  • Proper spacing and indentation
    • Nested lists work too
    • Multiple levels supported
  1. Install the baseline
  2. Write semantic HTML
  3. Customize with CSS variables
Classless
Styles HTML elements directly, without requiring class names.
Semantic baseline
A starting stylesheet that styles native elements, not a component or layout system.
Content, not layout
Acorn handles how content looks; your site handles how the page is arranged.

# Task Lists

Markdown task lists (- [ ] / - [x]) render with the bullet removed and the checkbox aligned:

  • Write semantic HTML
  • Drop in acorn.css
  • Build the rest

# Blockquotes

The best baseline gets out of your way and lets you focus on content.

Acorn philosophy

# Footnotes

Markdown footnote output is styled automatically — inline references, the endnotes block, and back-links — across the common parsers (markdown-it, GitHub/remark, PHP Markdown Extra).

Footnotes are the quiet asides of good writing.[1] They say the extra thing without interrupting the sentence,[2] and Acorn sets them in the accent color so they read as references, not stray brackets.

Click a reference to jump down — the note you land on highlights briefly so you can find it. The arrow returns you to where you were reading.

  1. The endnotes block is set apart with a rule, smaller and quieter than the body — like the small print it is. ↩︎

  2. Links inside a note still read fine, distinct from the back-link arrow. ↩︎

# Containers & Alignment

Acorn handles content width and how blocks sit in the flow. It is not a grid system — page layout is your stylesheet's job.

# Containers (region width)

Constrain a region to a reading width:

  • <main> — default reading width (60rem)
  • data-container="narrow" — narrower reading width (45rem)

# Block Alignment

Place or size a block in the flow. This mirrors the WordPress/Gutenberg align model:

  • data-align="left" / "right" — float with text wrap
  • data-align="center" — centered block
  • data-align="wide" / "full" — break out past the reading measure

See it in action in the Media section below.

# Wide Breakout

This section uses data-align="wide" to break out wider than the reading measure — good for images, data, or anything that needs more room.

# Interactive Elements

Native HTML5 interactive elements with built-in styling and accessibility.

# Disclosure Widgets

What makes Acorn different?

It styles semantic HTML out of the box — the baseline you start with, not a utility kit you build with. Write proper markup, get a styled page.

Can I customize everything?

Yes. Override the CSS custom properties — change --primary or --button-radius and it propagates everywhere those tokens are used.

# Progress & Meter

Upload progress: 67%

Storage usage: 60% used

Battery level: 15% remaining

# Dialog

Example Dialog

A native HTML dialog element styled by the baseline, with a dimmed backdrop and proper focus management.

# State

Loading: Processing...

Success: Saved successfully

Error: Something went wrong

# Forms

Complete form styling with accessible focus states.

# Form Example

Contact Information
Interests

# Button Variants

Standard

Disabled

Destructive

# Inline Form

# Tables

Tables styled by default. Wrap one in data-table for horizontal scroll on narrow screens.

Team
Name Role Location
John Doe Developer New York
Jane Smith Designer San Francisco
Bob Johnson Manager Chicago

# Media Elements

Images, video, and embedded content, responsive by default.

# Responsive Images

Carina Nebula captured by James Webb telescope
The Carina Nebula as captured by the James Webb Space Telescope. NASA, ESA, CSA, and STScI

# Image Alignment

Images float with data-align: Square crop of Carina Nebula this text wraps around the right-aligned image on wider screens and stacks normally on narrow ones. Use data-align="left", "right", or "center" for in-flow placement.

Anim, nisi ad pariatur. Pariatur exercitation adipiscing tempor est amet aute. Adipiscing tempor est amet, aute dolor. Amet aute dolor enim anim est esse. Dolor enim anim est, esse laborum sint. Est esse laborum sint, id duis ea cupidatat.

Stellar death captured by Webb telescope
Full-width image using data-align="full". NASA's Webb Captures a Dying Star's Final Performance

# Media Gallery

Use data-gallery for a responsive image grid:

Carina Nebula Carina Nebula square crop Stellar death Carina Nebula inverted

# Video

Wrap embeds in data-embed for a responsive 16:9 aspect ratio: