clairity.css 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '03182618c372285ec43b03d258e897e30bd664e63c7a6fb1233ee03bd17d2b4c'
+  data.tar.gz: 040110db6d633bbef9bf3d7afc77f6dd72e808e26ecb251bbe39f57645aac97f
+SHA512:
+  metadata.gz: 04f1f1637aad3a420dba9a51e226484001f117f404d19f353c90729dde1058c6a73fb4120bd07dbfe2316294a42c60d8c524ce4f4236e1ac8383a79e0504f84a
+  data.tar.gz: 8ac5c4c0462ac43df99c4312e6856b6a73e13973b504c9ad5ade8ed656c563d21dfa2a32ef65ce96e295d9d100a5bc18994b157d90256cd8eba2f56bd0eaf47c

data/.github/workflows/main.yml

@@ -0,0 +1,27 @@
+name: Ruby
+
+on:
+  push:
+    branches:
+      - master
+
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    name: Ruby ${{ matrix.ruby }}
+    strategy:
+      matrix:
+        ruby:
+          - '3.2.2'
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Set up Ruby
+      uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+        bundler-cache: true
+    - name: Run the default task
+      run: bundle exec rake

data/.gitignore

@@ -0,0 +1,66 @@
+# Ignore Mac DS_Store files.
+.DS_Store
+
+# Ignore bundler config.
+/.bundle
+/.ruby-version
+/.ruby-gemset
+
+# Ignore all logfiles and tempfiles.
+/log/*
+/tmp/*
+!/log/.keep
+!/tmp/.keep
+.sass-cache
+*.swp
+*.swo
+
+# Ignore pidfiles, but keep the directory.
+/tmp/pids/*
+!/tmp/pids/
+!/tmp/pids/.keep
+
+# Ignore storage (uploaded files in development and any SQLite databases).
+/storage/*
+!/storage/.keep
+/tmp/storage/*
+!/tmp/storage/
+!/tmp/storage/.keep
+/public/assets
+/public/uploads
+
+# Ignore master key for decrypting credentials and more.
+/config/master.key
+
+# Ignore Byebug command history file.
+.byebug_history
+
+# Ignore rspec reports and doc files
+.rspec_status
+/spec/reports/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+
+# Ignore local environment variables.
+/.env
+
+# Ignore redis dumps.
+/dump.rdb
+
+# Ignore jekyll files
+.jekyll-cache
+.jekyll-metadata
+_site
+
+# Ignore vendored files
+vendor
+
+# Ignore localhost certs.
+/localhost-cert
+
+# Ignore node_modules & yarn errors
+/node_modules
+/yarn-error.log

data/CHANGELOG.md

@@ -0,0 +1,423 @@
+# <samp class="clairity">clairity.css</samp> Changelog
+
+The early parts of this changelog are going to be a little ambiguous and incomplete, as a lot of the initial development happened in 2022 but was only documented (and released) in April 2023. We'll try to be better about that going forward.
+
+Expect pre-v1.0 releases to have many backwards incompatible changes, being primarily meant for testing and feedback as we experiment with different approaches to common challenges leading up to a production-ready release.
+
+
+## [Unreleased]
+
+This section is for recording changes committed since the last release.
+
+
+### `clairity.basic.css`
+
+
+### `clairity.classless.css`
+
+
+### `clairity.css`
+
+
+### `variables.css`
+
+
+### `palette.css`
+
+
+### `functions.css`
+
+
+### `icons.css`
+
+
+### `base.css`
+
+
+### `cosmetic.css`
+
+
+### `states.css`
+
+
+### `classes.css`
+
+
+### `components.css`
+
+
+### `utilities.css`
+
+
+
+
+## v0.1.0 - 2023-04-19
+
+These changes bring <samp class="clairity">clairity.css</samp> to present day, hence the bump to v0.1.0 rather than v0.0.4. This is also the first version to release on rubygems.
+
+
+### `variables.css`
+
+* tweak the `--small` font size from `0.9rem` to `0.875rem` for more differentiation with `--medium`
+* add the `--field-max` variable, set to `min(47ch, 100%)`, so that form fields can stretch to a reasonable (but not unreadable) length on larger screens, but take as much space as available on small screens
+
+
+### `palette.css`
+
+* similar to `--info`, `--success`, `--warning`, and `--error` semantic info colors, add semantic (icon) state colors `--valid` (green), `--invalid` (red) and `--unknown` (yellow), with `-high`, `-low` and `bg-` variants
+
+
+### `icons.css`
+
+* add `--i-home-edit`, `--i-mail-check`, `--i-mail-x`, `--i-send`, `--i-server-cog`, `--i-user-circle`, `--i-user-off` icons from tabler
+
+
+### `base.css`
+
+Base acts like a css reset in that it (re-)defines the default styles of all html (pseudo-)elements.
+
+* `<nav>`: set `fit-content` on the `height` property to prevent unwanted vertical expansion
+* contain and make input images (`[type=image]`) middle-align with its associated label
+* for form field elements (`<input>`, `<textarea>`, `<select>`, `<optgroup>`, `<option>`, and a `<fieldset>` in a `<form>`), replace `min(47ch, 100%)` value on the `max-width` property with the newly added `--field-max` variable
+* set `max-width` to `--field-max` on `<meter>` and `<progress>` elements as well
+
+
+### `cosmetic.css`
+
+Cosmetic adjustments typically tweak base styles for specific situations.
+
+* remove `<body>` grid from pages that don't have a `<main>` element but do have `<h1>` and/or `<p>` elements (aka, bare pages)
+
+
+### `states.css`
+
+* define link signifier `--icon`s on the element rather than its `::before` or `::after` pseudo-element, letting inheritance define it for the pseudos
+* move `mailto` link signifier icon to be `::after` the `href` link by default
+* add required field asterisk to required select field's labels as well
+* an `:empty` `<button>` inside an aria `[role=alert]` container is styled as a close ("`⨉`") button
+  * added an appropriate `:hover` state as well
+  * might want to move this base style to `cosmetic.css` (to allow it to remain part of the `classless` set of styles), or move the whole enchilada to `components.css` with the other button styles
+
+
+### `classes.css`
+
+* apply `width` and `margin-inline` on `100dvi` class to address the horizontal scrollbar issue (works in some cases, but not all)
+* add semantic state color classes `.valid`, `.invalid`, and `.unknown`
+* add `.i-home-edit`, `.i-mail-check`, `.i-mail-x`, `.i-send`, `.i-server-cog`, `.i-user-circle`, `.i-user-off` icon classes
+* add `.unadorned` class to remove `::before` and `::after` content, which is useful for adding a custom icon to an element that already has a default icon
+
+
+### `components.css`
+
+* remove top margin from the `:first-child` `<header>` in the `<body>`, typically because this header is meant to sit flush with the top of the page
+  * removed the `[role=banner]` selector from this rule, because a banner may not necessarily always sit at the top of the page (even if they often do), as they could be placed inside another container
+      * setting the `role` attribute to `banner` on one element is the [recommended way](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/Banner_Role) of designating the site/global banner
+* remove `.subtitle` from spanning a full flex row (was added in v0.0.3)
+* `.banner` component
+  * set `align-self` to `flex-start` so it sits flush with the top
+  * set `height` to `--banner-height`, which allows us to override it more easily if need be
+  * remove extra block margin set on `.banner menu`
+* make sure long-lived site links, like those in a site header, don't get the `:visited` link color, as it can be distracting/disorienting, by adding `[aria-label="primary"]` alongside `nav menu li` to visited links that get the `--link` (rather than `--visited`) color
+* unset unnecessary `color` property for `[aria-current="page"]` links, which makes the active page look "selected" in a nav menu
+* add `.warning` buttons with default, `.secondary`, and `.tertiary` variations and with concommitant `:hover` states
+* update colors of `.danger` buttons to be more visually harmonious
+  * add `.secondary` and `.tertiary` variations of `.danger` buttons
+* constrain `form .buttons` to `--field-max`
+* give `.roomy.buttons` some extra `gap`: `--ml` instead of `--s`
+* use container queries (yay!) to fix buttons floating and getting squished on narrower screens, by unsetting `<form>` and form `.buttons` `max-width` and expanding `.buttons` to `full` grid width
+  * we also set `<label>` `font-size` to `--small` (it otherwise inherits `--medium` from `<body>`)
+* remove setting `flex-direction` on a `.card` so that a single card by itself doesn't get mangled
+* when providing space for `aside` in the `.grid` in browsers (erm, firefox) not supporting `:has()`, revert testing for support of `:has()` using `selector(:has(+ *))` back to `selector(:has(*))`
+  * firefox has limited support for `:has()` currently, and it is therefore [recommended](https://www.bram.us/2023/01/04/css-has-feature-detection-with-supportsselector-you-want-has-not-has/#the-problem) that it be unused on firefox, but we're pre-release, so leave this on for now so we can see how bad it is in firefox
+
+
+### `utilities.css`
+
+* *rails-specific*: rails adds the `.button_to` class to field-less forms it creates with the `:button_to` helper, and while this mini-form looks like a button, it tries to take up space like a form
+  * taking advantage of this narrowly-targeted class, adjust widths on the form and its embedded `submit` button so it looks/behaves like other buttons
+  * TODO: this should probably go in `shims.css` if/when we decide to reintroduce it
+
+
+
+## v0.0.3 - 2023-04-18
+
+The changes encompassed by this release were largely completed by about October 2022 (~6 months prior), but recorded (and released) here for posterity.
+
+
+### General
+
+- in `README.md`, updated the release checklist with correct `git` command to push commits with (annotated) tags
+- added `icons.css` - a minimal set of svg icons exposed as CSS variables
+- emulating the nice developer ergonomics of icon fonts, we overhauled icons entirely so that we can
+  - use css variables to define svg icons (rather than being inline defined)
+  - use convenience classes to put icons anywhere with just a class definition
+  - have icons adjust to light/dark color schemes automatically
+  - have icons change color on hover (and generally be responsive to pseudo-classes)
+  - all these things together was surprisingly difficult cross-browser
+- added `functions.css` to `clairity.classless.css` even though it includes a few (optional) heading *classes* (.h1, .h2, .h3, etc.), because the fluid typography for headings is so useful
+- we've gone back and forth about the idea of including 
+  - `normalize.css` (as an alternative css reset)
+  - `clairity/shims.css` (to better support, or at least gracefully degrade for, legacy *markup/sites*), and 
+  - `clairity/legacy.css` (to gracefully degrade for older *browsers*)
+  - currently all of these are turned off (i.e., not imported in any <samp class="clairity">clairity.css</samp> entrypoint stylesheet)
+- added block-style comments to css files to differentiate the different sections more easily
+
+
+### `clairity.css` file
+
+- experimented with the new `@layer` css cascade layers feature, but commented it out for now because it breaks firefox dev tools
+
+
+### `variables.css`
+
+`variables.css` defines all the custom properties (css variables) used in <samp class="clairity">clairity.css</samp> other than the color palette, which is defined in `palette.css`.
+
+- `:root` (defines defaults for both light and dark modes): renamed a number of variables for better semantics
+  - moved `--grid` to `functions.css`
+  - added `--view-height` variable to set an element to the view height of the viewport
+  - changed `--column` from `10rem` to `min(41vw, 10rem)` to force at least 2 columns at narrow widths
+  - renamed `--size` (in the `--tiny` ... `--size` ... `--huge` rem relative font scale) to `--medium`
+  - renamed `--medium` (in the `--smallest` ... `--medium` ... `--largest` em relative font scale) to `--initial`
+  - renamed the `--thinnest` ... `--weight` ... `--boldest` font weight scale to `--lightest` ... `--regular` ... `--boldest`
+  - renamed `--line-height` to `--normal` and changed it from `1.5` to `1.45` for aesthetics
+  - renamed the `--slimmest` ... `--stroke` ... `--thickest` line/border thickness scale to `--thinnest` ... `--stroke` ... `--thickest`
+  - added contextual spacings for icons
+      - `--inline-padding` for positioning icons next to text
+      - `--button-padding` for positioning icons inside buttons
+  - added default icon color variables
+      - `--icon-color`
+      - `--icon-blend-mode` for use in certain inverted color cases (TODO: reinvestigate this)
+  - added the `--heading-inverse` logical text color for inverted heading color contexts (light on dark)
+  - made `--background` always be the `Canvas` system color by default, rather than as a backup (`var(--100, Canvas)`) because it turned out to use a slightly different shade on different browsers (lookin' at you safari), which we couldn't replicate easily
+- `:root (prefers-color-scheme: dark)`:
+  - added the `--action` logical text color variable for button text
+  - redefine `--icon-color` for dark color schemes
+  - redefine `--icon-blend-mode` for dark color schemes
+- `:root @supports (color: color-contrast(white vs white, black))`: this is primarily to compensate for safari
+  - comment out the redefinition of `--action` (can't remember why)
+
+
+### `palette.css`
+
+Note that the structure of the color palette, never mind the palette itself, is still very much in flux. Initially, we hoped that one of the new [LCH/okLCH color spaces](https://evilmartians.com/chronicles/oklch-in-css-why-quit-rgb-hsl) would provide a nice perceptually uniform, rich palette that could be programmatically generated and also predictably transformable using css color functions for any color we desired. We wanted to have our cake and to eat it too. But alas, neither LCH or okLCH are truly capable of hands-off, mechanical palette generation and transformation for any set of colors, because of issues like [the dark yellow problem](https://uxdesign.cc/the-dark-yellow-problem-in-design-system-color-palettes-a0db1eedc99d?gi=971e71981fd1). We still like okLCH for its other qualities and will use it where we can, but our hopes of auto-paletting purely in css were but a childlike dream.
+
+So with that said, the palette will probably move toward manually-adjusted sets of hue/chroma/lightness tuples in a large matrix of scales for each major color. This seems to be the way other modern frameworks are approaching the color palette issue, even with LCH/okLCH.
+
+- hues get a color name variable (e.g., `--blue` or `--red`) because it's difficult to decipher from the numerical value (210 or 4)
+  - this means that color names don't represent full colors, as it does in other css frameworks, because we prefer semantic colors for that instead (like `primary` over `blue`, or `accent` over `yellow`)
+- Because of the need for so many scales to define our full palette, we're breaking our general practice of using full semantic names to using short scale names composed of a letter and a number (which also makes our css rules more easily comprehended because the declarations are shorter and more uniform)
+  - HSL saturations are converted from `--saturated` and `--unsaturated` to `--s4` and `--s10` (saturation level 4 and saturation level 10)
+  - HSL lightnesses go from `--darken` and `--lighten` to `--l4` and `--l7`
+  - HSL alpha transparencies go from `--alpha` to `--a0` and `--a1` (these nearly transparent alphas are used to soften white and black toward the underlying hue)
+  - LCH chromas go from `--dullest` and `--richest` to `--c0` and `--c9` (still dullest to richest)
+  - LCH lightnesses also go from `--darkest` and `--lightest` to an `--l1` and `--l90` percentage scale
+    - added `--lighten`, `--darken`, and `--brighten` to `--lightness` as bridge values for LCH
+- EXPERIMENTAL: instead of `primary`, `secondary`, and `tertiary` colors (3 different colors), we define full color scales for `primary`, `secondary`, and `complementary` colors, with `complementary` being the opposing hue (180° difference) of `primary` rather than an independently chosen color. In theory, this should have provided a cohesive 3-color set without having to manually pick a third color, but in practice, the `primary` color needs to be carefully chosen so that the programmatically defined `complementary` color is not only acceptable but well-differentiated from the `secondary` color.
+- EXPERIMENTAL: for okLCH, we define only a color set of `--primary` through `--nonary` (9 colors) and complementary, triadic and tetradic colors (5 additional colors), with no color scales, and assume we'll transform colors on the fly using our chroma, lightness, and alpha scales as needed
+  - early indications are that this doesn't work nearly as well as we'd hoped
+
+
+### `functions.css`
+
+- added `.h1, .h2, .h3, .h4, .h5, .h6` classes to fluid typography heading rule
+- removed experimental relative color scale variables (`--0` through `--15`)
+- `<a>`, `<i>`, `<input>`: added the `--colorize-icon` "function" to add `--icon-color` to any icon via a `linear-gradient`
+- `<body>`, `<main>`, `<header>`, `<footer>`, `<aside>`, `<article>`, `<nav>`, `<section>`, `<div>`
+  - moved `--grid` variable for defining grid column widths here from `variables.css`
+  - added `--gap` "function" for fluid gap values
+  - moved `--padding` here from the `<body>` grid definition in `components.css` for fluid padding values
+  - this works in the common case but isn't quite as robust as we'd hoped (TODO: needs investigation)
+
+
+### `icons.css`
+
+Eventually, we want to have a consistent set of svg icons that are uniform and pleasing, but for now, we grab whatever we can from existing sources, so that we can figure out what the minimal set of icons we need are.
+
+- added 10 svg icons as css variables sourced from [almond.css](https://github.com/alvaromontoro/almond.css) and elsewhere (`--i-burger`, `--i-check`, `--i-chevron`, `--i-dash`, `--i-download`, `--i-external`, `--i-search`, `--i-sms`, `--i-tel`)
+- added 14 [tabler icons](https://tabler-icons.io/) as well (`--i-bookmark`, `--i-browser`, `--i-calendar`, `--i-calendar-time`, `--i-external-link`, `--i-edit`, `--i-file`, `--i-file-download`, `--i-lock`, `--i-mail`, `--i-message-2`, `--i-numbers`, `--i-phone`, `--i-trash`)
+
+
+### `base.css`
+
+- `*, *::before, *::after` (applies to all elements): moved non-essential defaults out of this rule (margin, padding, border, font-size, vertical-align), as `<svg>` documents can also fall under `*` (also `*` rules are less efficient, applying to everything, as it does, so minimize its use)
+- `<main>`, `<aside>`, `<article>`, `<nav>`, `<section>`, `<header>`, `<footer>`: EXPERIMENTAL - designate `inline-size` container name for these common container-type elements
+- `<body>`: make the body fill the viewport height, if content is not enough by itself to do so
+- `<hgroup>`: styled with a strong visual offset
+  - `<hgroup>` is deprecated but still useful for containing *just* heading elements, as opposed to all kinds elements, as `<header>` does)
+- `[href^="mailto:"], [href^="tel:"],    [href^="sms:"], [href^="file:"], [rel~="external"], [rel~="bookmark"], [download]`: move automatically included icon to the right instead of the left for these link types
+- `<menu>`: remove default left padding and list marker
+- `<th>`, `<td>`: add small top padding
+- `<form>`: change second grid column name from `fullwidth` to `full`
+- `::placeholder`: apparently needs font set explicitly
+- `::file-selector-button`: style like other buttons
+- `<select>`: reformat background image url for svg to fit better
+- `<meter>`, `<progress>`: apply uniform styling to these unruly elements (note that it requires lots of browser-specific pseudos to get working consistently cross-browser)
+- `<code>`, `<var>`: make just bold instead of bolder
+- `<hr>`: make horizontal rules span the full width of a containing grid
+
+
+### `cosmetic.css`
+
+This file includes cosmetic adjustments to the base elements, typically via combo selectors, which don't fit the scope of `base.css`.
+
+- make sectioning containers (`<header>`, `<nav>`, `<main>`, `<section>`, `<div>`, `<figure>` & `<footer>`) that are direct children of `<body>` readable by setting a max-width of `--line-length`, with a width of 100% for smaller screens and auto margins to center the blocks horizontally
+- headings in headers style rule moved here from `states.css`
+- unstyle `<ul>` in `<nav>` elements to let parent styles cascade
+- set grid column to `full` instead of `fullwidth` in accordance with the same change in `base.css`
+  - for unordered lists of checkboxes and radio buttons
+  - for form headers and paragraphs
+- set the `<select>` element's downward chevron background image to the `--i-chevron` icon variable
+- put left-side labels for checkboxes in the `elements` grid column, left-justified
+
+
+### `states.css`
+
+The big change here is using css variables for svg masked icons rather than inlining them in the css, so that we can just set any icon to the `--icon` variable to get it to show up. Note that this uses a finicky masking technique that needs to be more fully documented (TODO), but we were able to support hover effects and to get it to support both light and dark modes with some mucking about with `--icon-blend-mode` (set in `variables.css`).
+
+- `mailto`, `tel`, `sms`, `file`, `external`, `bookmark`, `download`: completely rewrote rules for link signifier icons
+- unset `--icon-color` on disabled elements' `:hover` state so disabled elements don't visibly hover
+- footnotes/endnotes styles moved to `components.css`
+- move headings in headers style rule to `cosmetic.css`
+- `<table>` styles
+  - excluded `<tfoot>` row headers from being sticky
+  - lower specificity of rule to skip hidden rows for alternate row highlighting by using `:where()`
+- change grid column from `fullwidth` to `full` in accordance with the same change in `base.css`
+  - for `<section>`, `<p>`, and `<div>` elements, as they're typically meant to span the full width of the form
+  - for any `<fieldset>` that contains other form elements, as it needs the full width of the form to display it's contents (once subgrid is fully supported, this will be easier)
+  - for headings, paragraphs, and divs in `<fieldset>` elements that don't contain form elements (typically that means these are top-level elements, rather than elements ascribed to form fields)
+- set `--icon-color` to `--primary` for `:focus`ed form fields (they're the `Field` system color when unfocused)
+- completely rewrote rules for form field signifier icons
+  - this employs a few tricks like our `--colorize-icon` "function" that applies a linear-gradient to color the icon, which layers the color down and uses the icon as a mask
+      - a direct application of color wouldn't work in all cases, for both dark & light modes and hover effects
+      - requires the svg icon to be white, so as to apply full masking effects and not distort the underlying color layer
+  - set the icon by setting `--icon` to one of the svg icon css variables from `icon.css`
+  - set icon color via the `--icon-color` variable (set to `--primary` by default for form fields)
+  - rewrote rule for `:indeterminate` checkboxes to use the new icon system (the "minus" icon is actually an svg)
+- remove unnecessary `:is()` from rule to disable border `:hover` effect on `:read-only` and `:enabled` fields (which aren't editable, so shouldn't highlight on hover)
+- using `:is()` instead of `:where()`, upped the specificity of the `:disabled` rule for radio buttons and checkboxes so it overrides the global `:disabled` and `:hover` rules
+- `::file-selector-button`: style its `:hover` and `:disabled` states like other buttons and ensure overriding specificity (the underlying pseudo-element rule is defined in `base.css`)
+- add a `:disabled` state to `<input>` of `type="file"`
+- don't let disabled `<select>` and `<option>` elements be hovered (for both attribute `[disabled]` and pseudo-class `:disabled` versions)
+- don't change border color on `:hover` for `<progress>`
+- for non-root `<svg>` elements, lower the specificity using `:where()` and remove the max-width restriction
+
+
+### `classes.css`
+
+`classes.css` encompasses mostly singular helper class rules, while `components.css` encompasses rules for multiple elements designed to work together. Meanwhile, `utilities.css` is for rules that proxy a single (or perhaps a couple related) underlying css declaration as a class.
+
+- added the `.icon` class for elements that want to include an icon
+- added `.leading` and `.trailing` classes for added space for `::before` and `::after` elements, typically icons
+- moved the `.container` class to `utilities.css`
+- moved `.grid` class to `components.css`
+- `.subgrid` - sets declarations related to being a subgrid element
+  - used `padded` instead of `paddedwidth` in accordance with the default `<body>` grid set in `components.css`
+  - use the `inherit` display value rather than `grid`, so that elements without a gridded parent can display normally
+  - unset max-width so that parent can dictate width
+- add the `100vw`/`_100vw` class: sets an element to the full width of the viewport, despite restrictions from the parent (e.g., a grid element)
+- add the `100dvi`/`_100dvi` class: similar to `100vw`, sets the width to the dynamic viewport width, but this still has horizontal scrollbar issues, despite the promise of fixing that
+- moved `.block` to `utilities.css`
+- renamed `.fullwidth` to just `.full` and set max-width to `none` to remove any other width restrictions so this element can span all grid columns
+- renamed `.paddedwidth` to just `.padded`; this class excludes the outer column on each side to the width of the element
+- add `.h1`, `.h2`, `.h3`, `.h4`, `.h5`, `.h6` classes: for styling elements equivalent to their respective heading elements with fluid typography
+  - NOTE: because plain css doesn't have mixins (yet, fingers crossed), we have to manually keep this style in sync with the headings styles defined in `base.css`
+- let `.p-subtitle` microformat class be equivalently styled like our `.subtitle` class
+- `.plain` removes decorations from elements (typically `<hgroup>`)
+  - added a rule to normalize the spacing (via margin-top) between heading elements for `.plain`-specified elements
+- moved `.button` classes to `components.css` (as buttons are really compact components with lots of little pieces, such as icons)
+- moved `.dual-aside` to `components.css` (as it's related to grid components)
+- added `--flex-break` to `.flex` to set a value to get elements to become single column when below this value
+  - added `flex-basis` to `.flex` children that uses this `--flex-break` value
+- added a `.section` class specifically for `<hr>` elements that visually separates sections more boldly
+- moved the `.clairity` class to `utilities.css`
+- added icon classes (as opposed to icon variables): `.i-burger`, `.i-check`, `.i-chevron`, `.i-dash`, `.i-edit`, `.i-mail`, `.i-trash`
+  - these allow constructs like `<i class="i-burger"></i>` to show an svg icon, similar to what font icon libraries do (e.g., fontawesome)
+
+
+### `components.css`
+
+- `<body>` has a default grid applied here
+  - rename `fullwidth` grid column name to just `full`
+  - rename `paddedwidth` grid column name to just `padded`
+  - moved definition of `--padding` "function" to `functions.css`
+  - exclude `<main>` elements that are children of `.grid` items from being `padded` width
+- comment out problematic margin-top removal from first `<header>` or `role=banner` element within `<body>`
+- let non-`.banner` `<header>` elements flex
+- let `<p>` and `.subtitle` elements in `<header>`s span a full flex row
+- redefine the `<footer>` grid to be columned
+  - let `<p>` children of `<footer>` span the full grid
+- add `.fat` component class for creating a fat footer with an inverted color scheme by default
+    - add `.nav` container class so consecutive `<nav>` children can align on the grid nicely
+      - TODO: unfortunately wasn't yet able to find a flexible and robust solution for this without a container class for the `<nav>` children
+    - headings in footers (typically nav set headings) get special visual treatment (`--muted` color and `--light` weight)
+    - links in footers (inverted context) get `--light` weight and `--whitish` (inverted) color with no text decoration by default, unlike regular links
+- footnotes/endnotes styles moved here from `states.css`
+  - added rule to make footnotes/endnotes span the full grid in cases where it's in a grid container (does nothing otherwise)
+- moved container (queries) definitions to `base.css` for sectioning elements
+- added helper class for `<i>` elements used solely for icon display
+  - our icon classes all start with `i-`, so we use the selector `i[class^='i-']`
+  - this applies an `--icon-color` (`--color` or `currentColor`)
+  - it masks it using the `--icon` with spacing `--field-icon`
+  - it sets the background-color to `--icon-color`
+  - it reserves space using `--inline-padding`
+  - it sets a min-height of `--ml` to prevent naked icons (with no accompanying text) from collapsing into a line
+- update `.banner` class to better contain it's content
+  - added `--content-width` variable to the `.banner` class to constrain `.content` children's widths
+  - unset height, max-height and background-color from `.banner`
+  - add block margin to `.banner` `<menu>` elements
+  - add the `.hero` class to the `.banner > img` rule
+  - remove default styling from `<figure>` elements in `.banner` elements
+- changed `.column` align-items declaration from `flex-start` to just `start`
+- inline-flex and center `<div>`s that are children of `<nav>`s
+- `<nav>` `<menu>` links shouldn't get a differentiated `:visited` color
+- don't unset the background-color of `type=search` elements in `<nav>`s
+- make a `[aria-current="page"]` link non-clickable to differentiate it from links to other pages
+- comment out rule setting padded on `nav.column` elements that are not direct children of `<aside>` due to visual issues
+- moved `.button` classes here from `classes.css`
+  - set color to `--background` in `.toggle` button style
+  - add `.danger` type button for dangerous actions
+  - add `.tertiary` type button for less common actions (`.secondary` is defined as an inverted color button for less prominence)
+- moved `.grid` classes here from `classes.css`
+  - rename `.form.grid` grid column name from `fullwidth` to `full`
+- moved `.dual-aside` here from `classes.css`
+- moved `<meter>` and `<progress>` pseudo-class definitions to `base.css` (which had the base element definitions already)
+
+
+### `utilities.css`
+
+- moved `.container` here from `classes.css`
+- moved `.block` here from `classes.css`
+- `.centered`, `.centered menu`: horizontally center text and menu items
+- `.center`: center flex content
+- `.right`: end-align flex content
+- `.shadow`: add a box shadow to an element
+- moved `.clairity` here from `classes.css`: sets a differentiating font for our favorite css framework!
+
+
+## v0.0.2 - 2023-04-15
+
+After a number of diversions, including developing a (as yet unreleased) Jekyll theme for <samp class="clairity">clairity.css</samp>, our attention is back on the core css framework. This release packages <samp class="clairity">clairity.css</samp> as a Rails engine so we can use it in our Rails projects.
+
+- First packaging as a gem, built as a Rails engine atop Railties
+- Puts all imported files in a subdirectory to clarify the hierarchy of files
+- `clairity.basic.css` - an alternate stylesheet that includes only `variables.css` and `base.css` to provide a solid base for building a simple site or perhaps your own css framework
+- `clairity.classless.css` - a classless alternative stylesheet that provides a rich and clean visual design but imposes no classes of its own
+- `[normalize.css](https://github.com/necolas/normalize.css)` (reformatted to our liking) - optional css normalization library that retains useful defaults
+- functions.css - provides a clamped, smoothly varying font size for headings
+- `cosmetic.css` - split out any non-core/composite rules involving html elements here
+- `states.css` - mainly for pseudo-classes and pseudo-elements
+- `classes.css` - for class-based rules as opposed to element-based ones
+- `components.css` - for composite html structures involving multiple elements
+- `utilities.css` - to house a limited number of utility styles like `.visually-hidden`
+- `shims.css` - a place to put styles meant to support graceful degradation for older sites (not browsers, that goes in `legacy.css`)
+
+
+## v0.0.1 - 2022-06-24
+
+<samp class="clairity">clairity.css</samp> was inspired by classless css libraries like `almond.css` and `sakura.css`, as well as a longing for a nice semantic, HTML-first css framework, like a modernized Semantic UI, but employing cutting-edge css features to remove the need for css tooling (i.e., Sass).
+
+- Start of development
+- `clairity.css` - the main entrypoint, which imports the other css files as desired
+- `variables.css` - structure css variables (custom properties) for flexible theming
+- `base.css` - add styling block for every html element, even if empty
+- `palette.css` - separate out the color scheme into its own css file

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+source "https://rubygems.org"
+
+# gem dependencies in clairity.css.gemspec
+gemspec