@semanticus/semanticus-css

v3.1.3

Published

23 days ago

lightweight CSS framework that prioritizes semantic HTML and ARIA-focused accessibility, with a small set of atomic utilities

Semanticus CSS

Semanticus is a lightweight CSS framework that prioritizes semantic HTML and ARIA-focused accessibility, with a small set of atomic utilities.

Vision

Contribute to a more accessible friendly world wide web.

Mission

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.

Core Principles

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.

Installation

Option 1: CDN (quick start)

<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">

Option 2: Install manually

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">

Option 3: NPM

npm install @semanticus/semanticus-css

import '@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 import syntax requires a bundler that supports CSS imports (e.g., Vite, Webpack, Rollup, or Parcel).

Check out the Palettes and Sizes guides for more options.

How It Works

Semanticus CSS is built on four complementary layers:

1. Semantic Styling

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>

2. Components

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>

3. Variants

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>

4. Utilities

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>

Starter HTML template

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 &copy; 2026</p>
      <a href="#">Contact Us</a>
    </nav>
  </footer>
</body>
</html>

Customization

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.

Browser Support

Semanticus CSS targets modern browsers based on the following Browserslist configuration:

Last 2 versions of each browser
Firefox ESR
No dead browsers

Development

Check out this How to setup the project inside the contributing guide.

About

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.

Why not just use Bootstrap or Pico CSS?

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.

Size comparison

| 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 |

License

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.

Acknowledgments

Semanticus CSS wouldn't exist without the incredible work of the authors of:

Pico CSS

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.

Bootstrap

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.