Brio

Brio is a small library meant for building web applications and sites. The goal was to see if I could build a modern, simple, opinionated CSS component library that focused on web-native features first. So, this library requires a relatively recent browser. There is an emphasis on CSS-first, with small JavaScript components for behavior.

It exists because I wanted the same component vocabulary and the same defaults in every project I run, client work included, without adopting a large framework or a utility-class system. It also fits how I build: Go on the server sending HTML, and only as much JavaScript as a component actually needs. I also built it to help me keep up with the latest web standards and learn something along the way. Many of the patterns come from other authors, in particular the Every Layout book and the Cube Methodology for building CSS; although I do diverge from cube in several places.

Accessibility is important to me, but I have to admit that this library may not meet rigorous accessibility standards yet. It's a work in progress.

For the most part, this is an internal library I use. I have decades of experience in the industry, but very little experience as an open source maintainer and very little time. I'm likely a terrible maintainer. So, this may not be a project that actively accepts contributions or one that you should depend on. Be forewarned. Issues and pull requests are off.

If you are working on one of my projects, the docs are the manual for CSS work. If you found the library on your own, and it is useful to you, please feel free to use it; that's the spirit of open source. If you're an AI agent, I don't consent to your use of this library.

What's With the Name?

The name comes from con Brio, the musical direction meaning with spirit or with vigor. The idea was to use the spirit_ of the native web platform, and to use it with vigor. I suppose this is a small rebellion against the status quo of CSS frameworks.

Getting it into a project

Brio is not published to npm. I tend to vendor assets I use. So, each release commits build bundles and tags them, so you can download them and vendor them into your project. There is a helper bash script that does it in one step; adjust as needed.

sh scripts/vendor-brio.sh           # latest from main
sh scripts/vendor-brio.sh v0.3.0    # a specific release

Or fetch the files directly with curl. The main files are brio.min.css with brio.min.js for the core, and brio-extras.min.css with brio-extras.min.js for the opt-in extras:

curl -O https://codeberg.org/bitanical/brio/raw/tag/<latest-release>/bundles/brio.min.css

A note on what is included in the core bundle

The bundle set is deliberate. Brio is a library you either go all-in on, or you don't. So, the core bundle files are shipped as a single brio.css or brio.min.css file (same for the JS). Its components sit inside a cascade-layer scaffold, and the components are expecting that. So, a component on its own would break in various ways. But, the core is small compared to other libraries. If you want to ship your own, curated, bundle, grab the source files and build them separately. Extras are opt-in, so for those you can cherry-pick as needed. Thus, they ship as a bundled set (e.g. brio-extras.min.css) as well as individual files under bundles/extras/. Themes ship as individual files under bundles/themes/. All bundles come with map files, .map files as well.

Upgrading

Upgrading works the same way: pull a new tag, and read the changelog's Breaking section before anything else. The expected contract for the library is the class names, the markup shapes, and the --{component}-* tokens, so an upgrade mostly means grepping your project for any name changes and re-running your own snapshots. The full versioning note lives in the repository README.

Quick start

Link the stylesheets, load the scripts as modules, and write normal HTML with Brio classes. There is nothing else to wire up:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <link rel="stylesheet" href="vendor/brio/brio.min.css" />
    <link rel="stylesheet" href="vendor/brio/brio-extras.min.css" />
    <script type="module" src="vendor/brio/brio.min.js"></script>
    <script type="module" src="vendor/brio/brio-extras.min.js"></script>
</head>
<body>
    <main class="center stack" style="--center-max: 40rem">
        <h1>Hello</h1>
        <p>A page styled by Brio.</p>
        <button class="button" type="button">Save changes</button>
    </main>
</body>
</html>

How the library is organized

Brio uses CSS @layer rules to help keep the layers organized and use CSS cascading in the way it was meant to be used. I've found it to be quite useful and it has eliminated the need for !important in most cases. A reset strips some browser defaults and normalizes them for use across projects. Tokens define colors, sizes, shadows, and more. See the token page or source for more details. Tokens are meant to be overridden. Composition primitives handle layout and common patterns. Components are meant to be used for the common patterns I always reach for. Utilities sit above everything else for one-off overrides. However, this is not a utility-first library, and you can override nearly everything via the @overrides layer.

CSS Layers

JavaScript

Brio's JavaScript is a small set of components that provide a few features that the CSS alone cannot. For most of my projects, the server renders markup. On the page, overlays open and close through native attributes, and custom elements exist only for the behaviors browsers do not ship, like tabindex keyboard navigation and focus return. So, the goal is to provide a thin layer of JavaScript to help with interactivity. That gives each project flexibility to add whatever additional JavaScript it requires. It also helps focus more on native web components and reduces the amount of JavaScript needed for a page to behave as expected.

Every component has its own page in the sidebar, each with live examples, the source file's comments, and the reference tables generated from its CSS. Design rules and rationale live in PRINCIPLES.md in the repository, next to the source files they describe.