Introduction

Actual CSS is a plain CSS component framework for new projects — semantic classes, small tokens, universal variants, theme hooks, and progressive enhancement, with no build step and no framework dependency.

Actual CSS claims a small set of global class names and keeps everything opt-in: components define structure, variants change the style, and intents set the color. It is designed for new projects and can coexist in existing ones through cascade layers, import order, or a project-owned build-time prefix transform.

CSS-first philosophy

• CSS owns layout, surfaces, state styling, and transitions.
• JavaScript is optional and completes the interactive components — dialog, flyout, tooltip, tabs, scrollspy, status bar, and more.
• Semantic markup comes first; behavior is a progressive enhancement layered on top of it.
• Prefer native platform features when they fit, with small helpers where browser support or ergonomics need it.
• Markup stays understandable without JavaScript, and modern features are gated with @supports so older browsers keep the core layout and controls.

Use classes for presentation, HTML and ARIA for meaning and state, data-enhance to enable behavior, and feature-specific data-* attributes to configure it. See Philosophy for the main principles and how to compose components.

Install

npm install actual-css

Import what you use. The simplest start is the package's full entry, copied into your project and pruned — see Start from the full entry:

@import "actual-css/css";                   /* core */
@import "actual-css/css/layout";
@import "actual-css/css/forms/all";
@import "actual-css/css/components/button";
@import "actual-css/css/components/card";
@import "actual-css/css/utilities";

actual-css/css is the core (reset, tokens, theme, base, intents, variants, focus, print). Each family and module is its own import; the modular import guide has the full map.

For zero-config use — prototypes, CDN, or when bundle size is not worth optimizing — the bare actual-css entrypoint and actual-css/full both resolve to the complete compiled framework:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/actual-css@0.16/dist/actual.full.min.css">

The package does not maintain separate partial bundles. Modular entrypoints map to source files, so each project composes the framework shape it needs.

Class grammar

Actual CSS uses a small unprefixed class grammar:

.component [intent] [variant] [size] [modifier]

• Intent: .primary, .secondary, .success, .warning, or .danger.
• Variant: .solid, .soft, .outline, or .surface. Buttons also support .ghost and .link.
• Size: .sm or .lg changes text and geometry on supported components.
• Density: .compact or .spacious changes spacing and geometry across a region, keeping text and icons at the same size.

Use data-theme to give a region a different palette. Undocumented is-* classes belong to the runtime.

<button class="btn">Click me</button>
<button class="btn primary">Save</button>
<button class="btn primary outline lg">Publish</button>
<button class="btn success soft sm">Confirm</button>

The JavaScript runtime

Some components can be enhanced with JavaScript: dialog, drawer, flyout, tooltip, tabs, scrollspy, context menu, floating UI, opt-in data-filter input filtering, and input masks. Presentation and behavior are separate layers — import the full runtime or any primitive independently to build custom widgets.

<script src="actual.full.js" type="module"></script>

import "actual-css/js/dialog";
import "actual-css/js/flyout";
import "actual-css/js/filter";
import "actual-css/js/mask";

JavaScript modules are safe to import during server-side rendering; outside a browser, registration is a no-op. The complete runtime contract — lifecycle rules, command routing, the floating and surface contracts, and how to extend the runtime — is documented in The JavaScript Runtime guide.

API surface

• Layout — the layout primitives: stack, cluster, grid, switcher, center, media, frame, app-shell, sidebar-layout, and more. See the Layout overview.
• Components — native and CSS-only component classes and examples: button, card, badge, alert, table, accordion, breadcrumb, pagination, skeleton, spinner, avatar, key, meter, progress, navbar, and more. Each component has its own page.
• Forms — field layout, controls, validation states, switches, selects, custom selects, and form actions. See the Forms overview.
• Enhancements — JS-enhanced component behavior: flyout, tooltip, tabs, scrollspy, and the status bar, each with its own page. See the Enhancements overview.
• Guides — Migrating from Bootstrap and Migrating from Tailwind walk through moving an existing project; The JavaScript Runtime documents the optional runtime that completes interactive components.

Beyond the pages, the repository keeps its design notes — browser support, cascade layers, naming, the enhancement contract, and widget primitives — as internal design documents for contributors.

Browser support

Actual CSS is built around progressive enhancement.

Degraded — semantic HTML and core CSS remain usable. JavaScript enhancements are outside the supported contract.

Minimal — full Actual support, including the JavaScript runtime. The runtime assumes modern browser APIs — including the native manual Popover transport used by interactive surfaces — and ships no legacy compatibility layers or polyfills.