Semanticus is a lightweight CSS framework that prioritizes semantic HTML and ARIA-focused accessibility, with a small set of atomic utilities.
Contribute to a more accessible friendly world wide web.
Enable authors to write clean, semantic HTML that looks great by default, guide them toward ARIA-centric patterns, and ensure core functionality works without JavaScript while allowing deliberate customization via a small, consistent set of utilities.
- Semantic-first: Semantic styling for real HTML elements and ARIA roles rather than relying on heavy class scaffolding.
- Accessibility-focused: Prefer ARIA patterns and semantic attributes over ad-hoc class-based components.
- Minimalism: Keep utility classes to a necessary minimum; add classes only for intentional overrides.
- Predictable customization: Centralize styling via CSS variables, assuring a consistent look for both semantic styles and atomic utilities.
- Progressive enhancement: Ensure base semantics work without JavaScript, and enhance behavior when needed.
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@semanticus/[email protected]/dist/semanticus.css">
<!-- costumize it with a palette or size variation if needed -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@semanticus/[email protected]/dist/semanticus.palette.blue.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@semanticus/[email protected]/dist/semanticus.size.pico.css">Download the distribution files, move the ones you need to your stylesheets folder and include them in your HTML <head>:
<link rel="stylesheet" href="/css/semanticus.css">
<!-- customize it with a palette or size variation if needed -->
<link rel="stylesheet" href="/css/semanticus.palette.blue.css">
<link rel="stylesheet" href="/css/semanticus.size.pico.css">npm install @semanticus/semanticus-cssimport '@semanticus/semanticus-css';
// Or import only the semantic layer
import '@semanticus/semanticus-css/semantics';
// Or add a palette / size on top
import '@semanticus/semanticus-css/palettes/blue';
import '@semanticus/semanticus-css/sizes/pico';Note: The
importsyntax requires a bundler that supports CSS imports (e.g., Vite, Webpack, Rollup, or Parcel).
Check out the Palettes and Sizes guides for more options.
Semanticus CSS is built on four complementary layers:
Beautiful default styles for plain ARIA-centric HTML — simply write plain HTML and Semantic Styling will make it look great by default.
<article>
<hgroup>
<h1>Hello World</h1>
<p>Look at me, I'm <strong>bold</strong> and <em>stylish!</em></p>
</hgroup>
<button>Get Started</button>
</article>Minimal set of reusable building blocks that extend the Semantic Styling - add a component when you need a specific UI pattern.
<article class="card">
<hgroup>
<h1>Hello World</h1>
<p>Look at me, I'm <strong>bold</strong> and <em>stylish!</em></p>
</hgroup>
<button>Get Started</button>
</article>CSS classes that tweak the Semantic Styling and Components - throw in a variant when you want to add or reduce visual flair.
<article class="card secondary subtle">
<hgroup>
<h1>Hello World</h1>
<p>Look at me, I'm <strong>bold</strong> and <em>stylish!</em></p>
</hgroup>
<button class="contrast">Get Started</button>
</article>Utility classes adapted to the same CSS variables as the Semantic Styling and Components for a consistent design - use them when you need fine-grained control over spacing, layout, colors, and more.
<article class="card secondary subtle shadow text-center w-75 mx-auto">
<hgroup>
<h1>Hello World</h1>
<p>Look at me, I'm <strong>bold</strong> and <em>stylish!</em></p>
</hgroup>
<button class="info ghost">Get Started</button>
</article>Here's an off-to-a-great-start HTML template using semantic styling, its variants, and utilities:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="color-scheme" content="light dark">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@semanticus/[email protected]/dist/semanticus.css">
</head>
<body class="content-grid">
<header>
<nav>
<a href="#" class="fs-3"><strong>Acme Corp</strong></a>
<ul>
<li><a href="#">About</a></li>
<li><a href="#" role="button" class="contrast">Log In</a></li>
</ul>
</nav>
</header>
<main class="py-d mb-3">
<hgroup>
<h1>Welcome to Semanticus CSS</h1>
<p>ARIA-centric, semantic HTML enhanced by atomic utilities.</p>
</hgroup>
<button>Get Started</button>
</main>
<footer class="full-width pane">
<nav>
<p>Acme Corp © 2026</p>
<a href="#">Contact Us</a>
</nav>
</footer>
</body>
</html>You can override its variables to create your own themes and styles. For example:
:root {
--primary-background-color: #4f46e5;
--primary-color: white;
--border-radius: 0.75rem;
--font-family: "Inter", sans-serif;
}Check out the CSS Variables guide for more details or the Palettes and Sizes builders to help you create your own custom styles.
Semanticus CSS targets modern browsers based on the following Browserslist configuration:
- Last 2 versions of each browser
- Firefox ESR
- No dead browsers
Check out this How to setup the project inside the contributing guide.
Semanticus CSS is inspired by the semantic and accessible foundations of Pico CSS and the flexibility of utility composition patterns popularized by Bootstrap.
It aims to address the friction that often appears shortly after installing Pico CSS, when you want to customize spacing, layout, colors, and other CSS properties. It does so by combining Bootstrap-style utilities adapted to the same CSS variable system.
Or any other full-fledged CSS framework, for that matter.
Semanticus CSS is not appealing solely because of its small footprint. Its real value lies in its semantic-first and accessibility-focused styling approach, helping developers build beautiful interfaces while gradually guiding them toward accessibility best practices without overwhelming them with the complexities of ARIA patterns and implementation details.
| Bundle | Gzip |
|---|---|
| Pico (semantics only) | 10.2 KB |
| Semanticus (semantics only) | 10.9 KB |
| Pico (semantics + classes) | 11.5 KB |
| Semanticus (semantics + components + variants) | 13.5 KB |
| Bootstrap (utilities + grid) | 16.3 KB |
| Semanticus (utilities + grid) | 10.6 KB |
| Bootstrap (full bundle) | 53.8 KB |
| Semanticus (full bundle) | 23.7 KB |
Semanticus CSS is licensed under the MIT License.
This project incorporates concepts and patterns from Pico CSS and Bootstrap, including Bootstrap's utilities system, both under the MIT License. See the NOTICE file for full attribution and copyright details.
Semanticus CSS wouldn't exist without the incredible work of the authors of:
For showing us the beauty and power of semantic HTML while using accessibility as part of the design. Very few frameworks have managed to keep so faithful to the semantic motto as PicoCSS is.
For providing a broad, practical utility system and a well-documented Utility API. Bootstrap's utility architecture strongly influenced the utility layer in this project.