@semanticus/semanticus-css

v0.8.0

Published

15 days ago

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

Downloads

758

Semanticus CSS

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

Vision

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

<!-- costumize 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 & Sizes guide for more options.

🚀 Usage

Semanticus CSS is built on three complementary layers:

1. Semantic Styling

Beautiful default styles for plain ARIA-centric HTML — no classes needed. See the Semantic Styling guide for more details.

<article>
  <h1>Hello World</h1>
  <p>Look at me, I'm <strong>bold</strong> and <em>stylish!</em></p>
  <button>Click me</button>
</article>

2. Variants

Minimal set of CSS classes that add visual variation to the Semantic Styling. See the Variants guide for more details.

<button class="ghost">Ghost</button>
<button class="secondary">Secondary</button>
<button class="contrast">Contrast</button>

3. Utilities

Utility classes for spacing, layout, colors, and more — adapted to the Semantic Styling and Variants values for a consistent design. See the Utilities guide for more details.

<footer class="py-4 text-center text-bg-contrast-subtle">
  <p class="mb-0">Star us on GitHub!</p>
</footer>

🛠️ Customization

You can override its variables to create your own themes and styles. For example:

:root {
  --color-primary: #4f46e5;
  --border-radius: 0.75rem;
  --font-family: "Inter", sans-serif;
}

Check out the CSS Variables guide for more details or the Theme Builder 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 Guide for instructions on setting up the development environment, running tests, and contributing to the project.

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