clairity.css is a responsive, semantic, classless CSS framework, with ambitions to grow into a complete (classful) design system one day. It's inspired by almond.css, sakura.css, normalize.css, Semantic UI, and others.
The core issue clairity.css addresses is making HTML simple and approachable. We've tried all the big CSS frameworks and all of them fail to present simple HTML as a first approach. We're not dogmatic about classless CSS or anything like that, but we'd sure as heck like to start with classless CSS first & then get fancier as needs dictate.
clairity.css was developed as an experiment to see how far the latest css features and semantic html can take you without the excess tooling of modern front-end development (like sass, less, postcss, node, yarn, webpack, react and all that jazz). While the first version of clairity.css is being released as a gem (for rails1), it's not rails-specific at all. The lib/assets/css directory in the gem can be taken and placed in any site's public-facing static assets directory and function without any installation procedure at all. Just include a css <link> to it in the <head> of any page (or page template).
clairity.css is currently a super bare-bones gem that narrowly provides framework assets to a rails app (in lib/assets for now, because it was created for a related rails project), with the goal to expand to at least jekyll and perhaps further, like how bootstrap-rubygem does.
The clairity.css gem depends on rails autoloading assets and has only been tested using the Sprockets asset pipeline so far.
The big caveat here is that we use css and js rather than stylesheets and javascript (or javascripts, but we're using rails 7.0+) in our asset paths, which is a non-standard configuration for rails, but is perfectly in accordance with many static site generators. This non-standard config (for rails) is implicitly hard-coded into the clairity.css gem, with plans to make it configurable in the future (or perhaps we can just symlink it?).
Install the gem and add to the application's Gemfile by executing:
$ bundle add clairity.css
or just add this line to your Gemfile manually and bundle install afterwards:
gem "clairity.css"
If bundler is not being used to manage dependencies, install the gem by executing:
$ gem install clairity.css
As noted in the intro, clairity.css has been released as a rails gem first, but can easily be used outside of rails (for static sites, for example) by putting the css assets in a place your site can reference it publicly.
Once the gem is installed, require clairity.css in your rails app's application.css. You can @import one of these three alternatives (or for firefox, set one as the primary, and the other two as alternate stylesheets):
clairity.basic.css - include only the custom properties (css variables) and element styles of clairity/variables.css and clairity/base.cssclairity.classless.css - beyond the basics above, this alternative includes the default color palette and other classless styles (clairity/palette.css, clairity/cosmetic.css, and clairity/states.css)clairity.css - this is the full-fat version that includes everything, including helpful classes and component definitions/*
* app/assets/css/application.css
*
* (we prefer 'css' over 'stylesheets' in our asset paths)
*
* This is a manifest file that'll be compiled into application.css, which will
* include all the files listed below.
*
* clairity.css lives in the css root of lib, `lib/assets/css`, and thus can be
* imported directly here. Put it before your `require_self` directive if you
* wish to extend those styles here
*
*# require_tree .
*= require clairity.css
*# require_self
*/
/* instead of the sprockets directive above, you can use a css @import directive: */
@import "clairity.css";
/* to get basic plus the palette, use two @import statements:
@import "clairity.basic.css";
@import "clairity/palette.css";
*/
The clairity.css file, along with it's siblings clairity.basic.css and clairity.classless.css, are entrypoint files, designed to relieve you of having to worry about importing the individual components of the clairity.css framework yourself. You just need to <link> or @import one of these in your app, depending on your needs and preferences. You can also write your own entrypoint file that includes the individual component files yourself, and not use one of these three predefined entrypoints.
Note that rails handles setting paths for, and autoloading, these files from our gem (because our gem is a rails engine), so we don't need to worry about prefixing any paths here.
There is one js file that can optionally be included (it's more of a placeholder than a necessary component):
// app/js/application.js (we prefer 'js' over 'javascript' in our asset paths)
//
//= require clairity.css.js
import "@hotwired/turbo-rails"
import "controllers"
Here we use a Sprockets directive to import clairity.css.js directly into the app (Sprockets will package clairity.css.js into application.js at asset compile time). Note that this is the (otherwise default) rails 7.0+ version of application.js so yours may look a little different.
Outside of rails, you just need to place the clairity.css and the clairity folder in a place that publicly accessible to the site/app. For instance, for a jekyll site, this might look like:
<!-- /_includes/head.html (subsequently to be included in a layout) -->
<head>
...
<link rel="stylesheet" href="/assets/css/clairity.css" title="clairity.css">
<link rel="alternate stylesheet" href="/assets/css/clairity.basic.css" title="basic clairity">
<link rel="alternate stylesheet" href="/assets/css/clairity.classless.css" title="classless clairity">
...
</head>
where the contents of /lib/assets/css/ in the gem was placed in the /assets/css/ directory of the jekyll site (a similar procedure would expose our clairity.css.js file to a site/app).
To preview clairity.css, check out the Spec Sheet.
For a quick and dirty (and totally insecure) way of previewing clairity.css, download (or clone the gem repo locally) and unpack the gem (gem unpack clairity.css-X.Y.Z.gem), and from within the gem directory, run a (single-line invocation) ruby web server2:
$ ruby -run -e httpd public -p 8000
You can then navigate to http://localhost:8000/clairity.html to view the spec sheet. Note that this exposes everything in the /public root directory, as well as the lib/assets directory (via a symlink), to retrieval in any browser on the local network, not just your own machine, so don't put anything sensitive in there (for instance, email addresses can be harvested, or worse, by unscrupulous actors).
After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment (but being an asset-only gem, there's not much to experiment with in ruby!).
To install this gem onto your local machine, run bundle exec rake install.
To release a new version (for gem owners), follow the release checklist in the next section (i.e., don't rake release yet, until we have everything set up the way we like it). TODO: consider automating using release-please.
To release this gem, follow these steps:
~/.gem/credentials are all set correctly to be able to push to github and rubygems (only gem owners can push to rubygems).bundle outdated and bundle update) for minor version bumps (should test major bumps first)rake test and fix any issuesassets directory (or just changed css files as the case may be) from lib to docs (our symlink trick doesn't work on github, so we really need to automate this)CHANGELOG.md is up to date with a summary of the changes since the last releaseX.Y.Z for the new release based on the magnitude of the changes and in accordance with semantic versioning (replace X.Y.Z with the actual version number here, and below, obviously)X.Y.Z in lib/clairity.css/version.rbGemfile.lock likely needs to be updated due to the version number change, so update it via bundle && git add Gemfile.locks.files array in clairity.css.gemspec with any new files outside the main gem directories (such as lib) that need to be packaged in the gem itselfgem build clairity.css.gemspecpkg directory: mv clairity.css-X.Y.Z.gem pkg (pkg is gitignored, so move the gem now to show a clean working directory)gem unpack clairity.css-X.Y.Z.gem in the pkg directory (and delete the resultant clairity.css-X.Y.Z folder when finished)git commit -m "with a descriptive commit message here" (or using our standard shortcut, git cm "message")git tag vX.Y.Z -am "summary of the tag" (calling git tag without a commit hash tags the last commit)git push --follow-tags (check that git remote points to origin at clairity/clairity.css with git remote -v)pkg directory) to rubygems: gem push clairity.css-X.Y.Z.gemBug reports and pull requests are welcome on GitHub.
Being my first gem, as simple as it is, this endeavor required a little research into how to package everything together properly. Besides the rubygems and bundler docs on creating (and releasing) gems, the two posts were helpful in getting everything working:
The gem is available as open source under the terms of the MPL-2.0 License.
the irony of initially releasing clairity.css for an asset pipeline is not lost here, but to be fair, it was used on a jekyll static site first. ↩
WEBrick is no longer included as a bundled gem as of ruby 3.0, but is a dependency for the ruby httpd server, so install via gem install webrick if need be ↩
FAQs
Unknown package
We found that clairity.css demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Rspack launches Rslint, a fast TypeScript-first linter built on typescript-go, joining in on the trend of toolchains creating their own linters.
Security News
Hacker Demonstrates How Easy It Is To Steal Data From Popular Password Managers
Security News
Oxlint’s new preview brings type-aware linting powered by typescript-go, combining advanced TypeScript rules with native-speed performance.