clairity.css 0.1.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7fc66e74a6d2155fe9f589d0b4b32ab365b6ac466c9319c8ddda90528d11e8c1
-  data.tar.gz: ef0b2fad496abd68562f0fa8cc45e25e003aba4e375b784f33cfab29bd22bbe3
+  metadata.gz: 7b72fdbcec2b2d980f9a9c29277faebfd6b98e20723458f1938bd59fe01f25c8
+  data.tar.gz: 19cfbc2063ec59d6d405cb289205817193c9fd8f8947702cd54bdde74c5df1f3
 SHA512:
-  metadata.gz: 54dc10253e7948c79ad1ae98e41bdac13c5ce2d11debb74228f340be56cb00df640c481e0ac0e326b7c398de8015a306781f2fdb7f98436f9645f3e2a84e3b42
-  data.tar.gz: b7b019ee3a275e1514edec06ac4ddff518dc644cb599c8b17abd507d01968aead9740aad7e21bd1b5f7ac6a9591f5e413d9d707674ff72fc2f1f91dd35580718
+  metadata.gz: 339dd3bb5d0d7967915ca022093d19b6dff439fca037a36d41c605b055d0467430813fe945cbc580a656e11dd8f21a7438c0e9dfc00da6af63ec3e6e43a67e98
+  data.tar.gz: 4efc8f1596a4f9857168ba445d1fcf26db8ad530aa01aa1e24f0901585239b67ca8c62c25764fd69670cc3d98afb25ab15b9a2929edea8ca8fea88bf47c4712e

data/CHANGELOG.md

@@ -4,55 +4,226 @@ The early parts of this changelog are going to be a little ambiguous and incompl
 
 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.
 
+Going forward, this changelog will use the [keep a changelog](https://keepachangelog.com/) format and version according to [semantic versioning](https://semver.org/).
+
 
 ## [Unreleased]
 
 This section is for recording changes committed since the last release.
 
-### General
+### Added
+
+
+### Changed
+
+
+### Deprecated
+
+
+### Removed
+
+
+### Fixed
+
+
+### Security
+
+
+## [v0.3.0] - 20230617
+
+### Added
+
+* [icons.css]: `--i-settings` icon and the associated `.i-settings` icon class in [classes.css]
+* [components.css]: added `.secondary` and `.tertiary` variations of the `::file-selector-button`, part of the `[type="file"]` input type
+
+### Changed
+
+* [base.css]: decreased height of `::file-selector-button` by `var(--xxs)` to better reflect relative weight of the file selector button in the form hierarchy
+  * also removed `padding-inline-start` from the `[type="file"]` input type to vertically line up with other fields in a form
+* [components.css]: converted `.alert` class declarations into `[role="alert"]` attribute declarations to better reflect semantics and to be more accessible
+  * also updated `classes.html` alert box examples to use `[role="alert"]` rather than `.alert`
+* [cosmetic.css]: make labels inline-grids so they take up the full row height - EXPERIMENTAL
+
+
+## [v0.2.0] - 20230504
+
+This release focused on three distinct improvements:
+
+  1. fixing/updating `palette.css` so that HSL and okLCH palette sets are harmonious and complete
+  1. fixing full-bleed layouts for hero headers and fat footers
+  1. adding documentation pages (all still very much works-in-progress) to flesh out both the content and structure of our fledgling documentation set
+
+One note related to the palette: okLCH officially lands in Firefox next week with [version 113](https://developer.mozilla.org/en-US/docs/Mozilla/Firefox/Releases/113) (the last major browser engine to do so), so we'll deprecate the HSL palette set in a year or so, and move on to primarily using okLCH then.
+
+
+### Added
+
+
+#### [clairity.css]
+
+* now importing `shims.css` in `clairity.css` by default (previously commented out) to be able to start moving css that is specifically meant to support non-semantic but common ("legacy") markup styles (like adding `<div>` tags around form inputs) there
+* added `legacy.css` for supporting legacy (prior to ~2020) browsers (as opposed to "legacy" markup, which is what `shims.css` adresses)
+* added future `print.css` `@import` line, as a TODO marker
+
+#### [palette.css]
 
+* better described the structure of `palette.css` in the opening comments
+* expanded the saturation scale (HSL only)
+* explicitly define the primary (9 colors) & complementary (5 colors) color sets for both HSL & okLCH
+* provide full color scales for `--primary`, `--complementary`, `--secondary`, and `--neutral` colors for both HSL & okLCH
+* provide semantic color sets for both HSL & okLCH
+  * messaging colors: `--info`, `--success`, `--warning`, `--error`
+  * state colors: `--valid`, `--invalid`, `--unknown`
 
-### `clairity.basic.css`
 
+#### [base.css]
 
-### `clairity.classless.css`
+* noted that a `<meta charset="utf-8">` declaration is needed to get certain non-Latin glyphs (like open-quote in blockquotes) to render correctly
+* added `form` as an element that gets a default `container-name` applied for `inline-size` containment/container queries
 
+#### [cosmetic.css]
 
-### `clairity.css`
+* make bare divs in the default body grid exclude the outermost columns (aka be "padded") by default
+* add a default `--l` (large) top margin to the site footer &mdash; that is, `footer:last-of-type` within the `<body>` element, which is not a perfect proxy for the site footer as it presumes a given html structure, but as close as we can get for now
+* rather than being confined to the `elements` grid column, let fieldsets span the `full` grid of a parent form container on narrower width viewports (`<= 35rem`), and give the legend a slightly de-emphasized treatment as well
 
 
-### `variables.css`
+#### [states.css]
+* in accordance with other read-only input types, remove borders for `<input>` that don't have a `type` attribute if `:read-only` and `:enabled`
 
+#### [components.css]
 
-### `palette.css`
+* added `HACK` to better contain `<footer>` elements that have the `.100dvi` class applied to them to create a full-bleed (fat) footer
+* added container query to add `--s` (small) `padding-inline` to non-`.hero`/`<img>` `.banner` elements at container sizes `<= 50rem` (800px @ 16px/rem), because there would be no inline padding/margin otherwise and content would abut the viewport edges
+* added a `max-width` to `search` inputs of `100cqi` (100% of container width) to keep it from breaking out of the containing form (this helps the `.button_to` mini-form component in particular)
+* added `.tag` class to `.tags > li` rule styling tags (this should probably be a separate rule in `classes.css` and kept in sync with `.tags > li` until css mixins become a reality, if ever)
 
+#### [utilities.css]
 
-### `functions.css`
+* added a general `prefers-reduced-motion` rule [as recommended](https://css-tricks.com/a-complete-guide-to-css-media-queries/#aa-accessibility)
 
 
-### `icons.css`
+#### Documentation
 
+* added `classes.html`, `components.html`, `grid.html`, and `palette.html` doc pages (still works in progress)
+* added `dropin.html` and `cssbed.html` sample pages, to showcase shimming for alternate html structures
+* added `site.webmanifest` to `docs` and `public` folders, mainly for [declaring favicons portably](https://evilmartians.com/chronicles/how-to-favicon-in-2021-six-files-that-fit-most-needs)
+* added a version of the Navier-Stokes equation (which describes fluid flows) to docs as another slightly more complicated example of MathML
 
-### `base.css`
 
+### Changed
 
-### `cosmetic.css`
 
+#### [palette.css]
 
-### `states.css`
+* consolidated lightness scale for HSL & okLCH (using percentages)
+* 
 
+#### [cosmetic.css]
 
-### `classes.css`
+* moved numerous non-state related css rules here from cosmetic.css
+  * icons for specialized links
+  * scroll-margin for elements with an `id` property
+  * removing vertical gaps between consecutive unordered/ordered lists
+  * sticky table styles for `<thead>`, `<tbody>`, and `<tfoot>`
+  * zebra striping for table rows
+  * unstyling unordered lists in forms (because they typically list out form controls like checkboxes/radio buttons rather than text)
+  * implementing the default form grid on `<fieldset>` elements
+  * extending grids into container subelements, `<section>`, `<p>`, and `<div>` (using `<p>` this way is un-semantic, but not uncommon), and fix the placement of checkboxes/radio buttons and their labels
+  * aligning labels to top for `<textarea>` and multiple `<select>` elements, which are typically multi-line in height
+  * respecting an `<input>` element's `size` property when set (we typically force form controls to fit the standard form grid)
+  * adding context icons for specialized form inputs
+  * adding gaps between inline radios/checkboxes for readability
+  * removing search decorations on search boxes
+  * styling `<blockquote>` elements
+  * adding context to `<q>` elements with a `cite` property (i.e., citations)
+  * adjustments for `<figure>` elements containing headings or blockquotes
+  * constraining non-root `<svg>` elements by default in a document
+  * styling `<dialog>` elements for better usability
+  * styling `<details>` elements in accordian configurations
+* for `<section>`, `<p>`, and `<div>` elements within forms, `display` is set to `contents` (which acts as if the container isn't there), so also unset the element's `container-type` so it can respond to container queries on the parent container (which should be the form itself in most cases)
 
+#### [states.css]
 
-### `components.css`
+* moved numerous non-state related css rules to cosmetic.css (see above)
 
+#### [classes.css]
 
-### `utilities.css`
+* moved `body > *:not(.fluid)` rule to `legacy.css`
+* moved `.subgrid` alternative rules for browsers not supporting subgrid into `legacy.css`
+* moved experimental non-semantic color classes (like `.red`) to `utilities.css`
+* moved `.grid` and `.flex` layout classes into `components.css` as they're more component-like than simple class declarations
+* removed extra negative margin (`--xs` / `--s`) on `margin-inline` for the `.100vw` and `.100dvi` classes because it was causing centering and scrollbar issues at certain viewport widths
+* tentatively removed the `max-width: none;` declaration on the `.full` class because it interferes with applying `.full` within `.subgrid`
+* renamed the `.section` class to `.sectioning` to reduce confusion with the `<section>` element
 
+#### [components.css]
 
+* moved `.grid` and `.flex` component layout classes here from `classes.css`
+* make `<header>` elements that don't have `.banner` applied align its items to the `baseline` so that flexed text in the header lines up visually
+* add `.subtitle` (along with `<p>`) to `<header>` subelements that flex to a full row, which forces a line wrap
+* `unset` `max-width` on `.banner` items to negate `<header>` `max-width` being set to `--line-length` by default in `cosmetic.css`
+* set `max-width` on `.content` and `<nav>` items in `.banner` to `100dvi` to keep `.content` and `<nav>` from overflowing the `.banner` in full-bleed situations
+* for `.banner` `<nav>` direct children, set `place-self` to `flex-start center` rather than `start center` to account for flex
+* moved `.button_to` mini-form (a rails-specific construct) rules here from `utilities.css`
+* moved `.card`/`.cards` media query rules for browsers that don't support container queries from here to `legacy.css`
+* moved `.tags + .buttons` rule for browsers that don't support `:has()` from here to `legacy.css`
+* moved `.dual-aside` class to `classes.css`
 
-## v0.1.2 - 2023-04-21
+#### [utilities.css]
+
+* moved experimental non-semantic color classes (like `.red`) to here from `classes.css`
+* moved `.button_to` mini-form (a rails-specific construct) rules to `components.css`
+
+#### Documentation
+
+* implement the [keep a changelog](https://keepachangelog.com/) format
+* rewrote the copy on the `index.html` page (still a work in progress) to be more generally descriptive of the <samp class="clairity">clairity.css</samp> framework
+* copied `index.html` and its sample hero image to the `public` folder, for parity with the `docs` folder (TODO: remove `public` in favor of `docs` for local testing)
+* in the `docs/css` folder, separated out of `clairity.html.css` the palette-related sample css into `palette.html.css` for reuse in the `palette.html` doc page while also remaining in `clairity.html.css` as an `@import`
+* updated header and footer links on existing docs/public pages (`index.html`, `about.html`, & `clairity.html`) to include newly added pages
+
+
+
+### Deprecated
+
+
+#### Documentation
+
+* deprecated the `public` folder for local testing, in favor of the `docs` folder, which also serves as the [docs site](https://css.clairity.blog) on github (TODO: still need to deal with symlinks for the `assets` and `css` directories, for serving local assets without duplication)
+
+
+### Removed
+
+#### [palette.css]
+
+* removed non-numeric/semantic lightness and chroma scales in favor of uniform numeric scales (okLCH)
+
+#### [components.css]
+
+* removed `padding-inline` as a default from `footer` elements
+* removed unnecessary and funky `flex-basis` calculation on `<nav>` elements inside `.nav` containers that create odd wrapping situations on `<nav>` elements at certain larger viewport widths
+
+### Fixed
+
+#### [base.css]
+
+* put buttons (`button`, `[type="button"]`, `[type="submit"]`, `[type="reset"]`, and `::file-selector-button`) in the `elements` `grid-column` by default (forms default to 2-column grids), so they sit under form elements rather than under the labels
+
+#### Documentation
+
+* remove unused `.home` class on the `<body>` of `index.html`
+* remove unnecessary `.readable` class on the `<body>` and the `.full` class on `<main>` of `about.html`, which breaks the fat footer
+* removed unnecessary `.readable` class on the `<body>` of `clairity.html`, which breaks the fat footer
+* clarify in `README.md` when/why gem is moved to the `pkg` directory
+
+
+### Security
+
+
+
+
+## [v0.1.2] - 2023-04-21
 
 The big change here is fixing the color palette, which was left in an inconsistent state after attempting to use css relative color syntax, which is very much not ready for prime time. We also still need to fix accent coloring for differentiated text (e.g., `<code>`, `<var>`, `<pre>`, `<xmp>`, `<kbd>`) when using okLCH rather than HSL (TODO).
 
@@ -67,7 +238,7 @@ Our experiment using the perceptually-uniform (but not volumetrically-uniform) o
 * add spec page stylesheet (`clairity.html.css`) to show a full sample color palette in both hsl and oklch color spaces (most, if not all, sites will not have 9 brand colors, so we don't define all of these in the framework itself)
 
 
-### `variables.css`
+### [variables.css]
 
 Note that `variables.css` defines logical/semantic colors to be used in sites/apps while `palette.css` defines the color palette to which logical colors are mapped, decoupling semantic meaning from the underlying color definition (we dove headlong into the naming things problem).
 
@@ -77,7 +248,7 @@ Note that `variables.css` defines logical/semantic colors to be used in sites/ap
 * for dark mode, lighten the `--link` color a bit
 
 
-### `palette.css`
+### [palette.css]
 
 
 * add `--a2` to alpha transparency scale (not sure if we need a full scale here or not)
@@ -85,32 +256,32 @@ Note that `variables.css` defines logical/semantic colors to be used in sites/ap
 * add okLCH version of the `--primary` color scale (this fixes most of the mismatched/missing color problems when using okLCH)
 
 
-### `cosmetic.css`
+### [cosmetic.css]
 
 * links in headings shouldn't be differentiated by color, to reduce visual distraction
   * set the `--heading` color explicitly on heading elements (an equivalent from for heading classes is set in `classes.css` to avoid violating our no classes rule for `cosmetic.css`)
   * add the `:visited` state (which only applies to `<a>` and `<area>` elements that have an `href`) to the elements this rule applies to
 
 
-### `classes.css`
+### [classes.css]
 
 * restore `width` and `margin-inline` on `100dvi` class to address the horizontal scrollbar issue (works in some cases, but not all)
 * as in `cosmetic.css` with heading elements, set the `--heading` color explicitly on unvisited and `:visited` links in heading classes
 
 
-### `components.css`
+### [components.css]
 
 * explicitly set `z-index` to `0` (creating a stacking context) on a `.banner` `.content` block, as safari uses source order otherwise, as a `.banner` hero image has a z-index of `-1` (and otherwise sits on top of `.content` if it comes before the image in the source)
 * remove the superfluous `a` designation on `:visited` in the rule to color `[aria-label="primary"]` and `nav menu li` links with the `--link` color, as it unnecessarily increases specificity and `:visited` only applies to `<a>` and `<area>` elements with an `href` anyway
 
 
-## v0.1.1 - 2023-04-19
+## [v0.1.1] - 2023-04-19
 
 * github added `docs` directory with a `CNAME` file to deploy to github pages (the gemspec doesn't need this file, since it's for github only)
 * added sample `index.html` to docs directory to see it in action
 
 
-## v0.1.0 - 2023-04-19
+## [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.
 
@@ -121,23 +292,23 @@ These changes bring <samp class="clairity">clairity.css</samp> to present day, h
   * note that `Gemfile.lock` might change, so `bundle` it again if need be
 
 
-### `variables.css`
+### [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`
+### [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`
+### [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.css]
 
 Base acts like a css reset in that it (re-)defines the default styles of all html (pseudo-)elements.
 
@@ -147,14 +318,14 @@ Base acts like a css reset in that it (re-)defines the default styles of all htm
 * set `max-width` to `--field-max` on `<meter>` and `<progress>` elements as well
 
 
-### `cosmetic.css`
+### [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`
+### [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
@@ -164,7 +335,7 @@ Cosmetic adjustments typically tweak base styles for specific situations.
   * 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`
+### [classes.css]
 
 * temporarily remove `width` and `margin-inline` on `100dvi` class to address the horizontal scrollbar issue
 * add semantic state color classes `.valid`, `.invalid`, and `.unknown`
@@ -172,7 +343,7 @@ Cosmetic adjustments typically tweak base styles for specific situations.
 * 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`
+### [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
@@ -196,7 +367,7 @@ Cosmetic adjustments typically tweak base styles for specific situations.
   * 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`
+### [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
@@ -204,7 +375,7 @@ Cosmetic adjustments typically tweak base styles for specific situations.
 
 
 
-## v0.0.3 - 2023-04-18
+## [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.
 
@@ -227,12 +398,12 @@ The changes encompassed by this release were largely completed by about October
 - added block-style comments to css files to differentiate the different sections more easily
 
 
-### `clairity.css` file
+### [clairity.css]
 
 - 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]
 
 `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`.
 
@@ -261,7 +432,7 @@ The changes encompassed by this release were largely completed by about October
   - comment out the redefinition of `--action` (can't remember why)
 
 
-### `palette.css`
+### [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.
 
@@ -281,7 +452,7 @@ So with that said, the palette will probably move toward manually-adjusted sets
   - early indications are that this doesn't work nearly as well as we'd hoped
 
 
-### `functions.css`
+### [functions.css]
 
 - added `.h1, .h2, .h3, .h4, .h5, .h6` classes to fluid typography heading rule
 - removed experimental relative color scale variables (`--0` through `--15`)
@@ -293,7 +464,7 @@ So with that said, the palette will probably move toward manually-adjusted sets
   - this works in the common case but isn't quite as robust as we'd hoped (TODO: needs investigation)
 
 
-### `icons.css`
+### [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.
 
@@ -301,13 +472,14 @@ Eventually, we want to have a consistent set of svg icons that are uniform and p
 - 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`
+### [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)
+  - see https://www.tpgi.com/subheadings-subtitles-alternative-titles-and-taglines-in-html/
 - `[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
@@ -320,7 +492,7 @@ Eventually, we want to have a consistent set of svg icons that are uniform and p
 - `<hr>`: make horizontal rules span the full width of a containing grid
 
 
-### `cosmetic.css`
+### [cosmetic.css]
 
 This file includes cosmetic adjustments to the base elements, typically via combo selectors, which don't fit the scope of `base.css`.
 
@@ -334,7 +506,7 @@ This file includes cosmetic adjustments to the base elements, typically via comb
 - put left-side labels for checkboxes in the `elements` grid column, left-justified
 
 
-### `states.css`
+### [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`).
 
@@ -366,7 +538,7 @@ The big change here is using css variables for svg masked icons rather than inli
 - for non-root `<svg>` elements, lower the specificity using `:where()` and remove the max-width restriction
 
 
-### `classes.css`
+### [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.
 
@@ -398,7 +570,7 @@ The big change here is using css variables for svg masked icons rather than inli
   - 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`
+### [components.css]
 
 - `<body>` has a default grid applied here
   - rename `fullwidth` grid column name to just `full`
@@ -447,7 +619,7 @@ The big change here is using css variables for svg masked icons rather than inli
 - moved `<meter>` and `<progress>` pseudo-class definitions to `base.css` (which had the base element definitions already)
 
 
-### `utilities.css`
+### [utilities.css]
 
 - moved `.container` here from `classes.css`
 - moved `.block` here from `classes.css`
@@ -458,7 +630,7 @@ The big change here is using css variables for svg masked icons rather than inli
 - moved `.clairity` here from `classes.css`: sets a differentiating font for our favorite css framework!
 
 
-## v0.0.2 - 2023-04-15
+## [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.
 
@@ -476,7 +648,7 @@ After a number of diversions, including developing a (as yet unreleased) Jekyll
 - `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
+## [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).
 
@@ -485,3 +657,30 @@ After a number of diversions, including developing a (as yet unreleased) Jekyll
 - `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
+
+
+[unreleased]: https://github.com/clairity/clairity.css/compare/v0.3.0...HEAD
+[v0.3.0]: https://github.com/clairity/clairity.css/compare/v0.2.0...v0.3.0
+[v0.2.0]: https://github.com/clairity/clairity.css/compare/v0.1.2...v0.2.0
+[v0.1.2]: https://github.com/clairity/clairity.css/compare/v0.1.1...v0.1.2
+[v0.1.1]: https://github.com/clairity/clairity.css/compare/v0.1.0...v0.1.1
+[v0.1.0]: https://github.com/clairity/clairity.css/compare/v0.0.3...v0.1.0
+[v0.0.3]: https://github.com/clairity/clairity.css/compare/v0.0.2...v0.0.3
+[v0.0.2]: https://github.com/clairity/clairity.css/compare/v0.0.1...v0.0.2
+[v0.0.1]: https://github.com/clairity/clairity.css/releases/tag/v0.0.1
+
+[clairity.basic.css]: https://github.com/clairity/clairity.css/blob/master/lib/assets/css/clairity.basic.css
+[clairity.classless.css]: https://github.com/clairity/clairity.css/blob/master/lib/assets/css/clairity.class.css
+[clairity.css]: https://github.com/clairity/clairity.css/blob/master/lib/assets/css/clairity.css
+[variables.css]: https://github.com/clairity/clairity.css/blob/master/lib/assets/css/clairity/variables.css
+[palette.css]: https://github.com/clairity/clairity.css/blob/master/lib/assets/css/clairity/palette.css
+[functions.css]: https://github.com/clairity/clairity.css/blob/master/lib/assets/css/clairity/functions.css
+[icons.css]: https://github.com/clairity/clairity.css/blob/master/lib/assets/css/clairity/icons.css
+[base.css]: https://github.com/clairity/clairity.css/blob/master/lib/assets/css/clairity/base.css
+[cosmetic.css]: https://github.com/clairity/clairity.css/blob/master/lib/assets/css/clairity/cosmetic.css
+[states.css]: https://github.com/clairity/clairity.css/blob/master/lib/assets/css/clairity/states.css
+[classes.css]: https://github.com/clairity/clairity.css/blob/master/lib/assets/css/clairity/classes.css
+[components.css]: https://github.com/clairity/clairity.css/blob/master/lib/assets/css/clairity/components.css
+[utilities.css]: https://github.com/clairity/clairity.css/blob/master/lib/assets/css/clairity/utilities.css
+[shims.css]: https://github.com/clairity/clairity.css/blob/master/lib/assets/css/clairity/shims.css
+[legacy.css]: https://github.com/clairity/clairity.css/blob/master/lib/assets/css/clairity/legacy.css

data/README.md

@@ -63,7 +63,9 @@ Once the gem is installed, require <samp class="clairity">clairity.css</samp> in
  *# 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";
@@ -113,7 +115,7 @@ where the contents of `/lib/assets/css/` in the gem was placed in the `/assets/c
 
 ## Previewing <samp class="clairity">clairity.css</samp>
 
-(TODO: put spec sheet online and link it here)
+To preview <samp class="clairity">clairity.css</samp>, check out the [Spec Sheet](https://css.clairity.blog/clairity.html).
 
 For a quick and dirty (and totally insecure) way of previewing <samp class="clairity">clairity.css</samp>, 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 server[^webrick]:
 
@@ -130,7 +132,8 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 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).
+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](https://dev.to/ajrom/release-please-ci-deployment-for-ruby-gems-4md6).
+
 
 
 ### Release Checklist
@@ -147,14 +150,13 @@ To release this gem, follow these steps:
 1. update the version number `X.Y.Z` in `lib/clairity.css/version.rb`
 1. `Gemfile.lock` likely needs to be updated due to the version number change, so update it via `bundle && git add Gemfile.lock`
 1. update the `s.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 itself*
-1. build the gem with `gem build clairity.css.gemspec` (likely in the project root directory, but that's ok for now)
+1. build the gem with `gem build clairity.css.gemspec`
+1. manually (as it doesn't do it automatically, despite what the docs say) move the gem package to the `pkg` directory: `mv clairity.css-X.Y.Z.gem pkg` (`pkg` is gitignored, so move the gem now to show a clean working directory)
 1. (optional) confirm the gem contents by unpacking it with `gem unpack clairity.css-X.Y.Z.gem` in the `pkg` directory (and delete the resultant `clairity.css-X.Y.Z` folder when finished)
 1. `git commit -m "with a descriptive commit message here"` (or using our standard shortcut, `git cm "message"`)
 1. tag the newly-created commit with an annotated tag `git tag vX.Y.Z -am "summary of the tag"` (calling `git tag` without a commit hash tags the last commit)
 1. push the commit *with annotated tags* to github: `git push --follow-tags` (check that git remote points to `origin` at `clairity/clairity.css` with `git remote -v`)
-1. push the gem (sitting in the project root directory) to rubygems: `gem push clairity.css-X.Y.Z.gem`
-1. manually (as it doesn't do it automatically, despite what the docs say) move the gem package to the `pkg` directory: `mv clairity.css-X.Y.Z.gem pkg`
-
+1. push the gem (from the `pkg` directory) to rubygems: `gem push clairity.css-X.Y.Z.gem`
 
 ### Contributing