UpdatedFixed
Custom properties have been completely overhauled in this release, with a new primitive and semantic design tokens approach. This makes theming easier and more logical. Read more about this approach in the theming docs.
I’ve also made a bunch of improvements to the documentation website, including reorganising the getting started section and adding of a theme toggle, for those that prefer reading in dark mode.
Expect breaking changes if you decide to update to this version.
Improvements #
Core boilerplate #
- Semantic color tokens replace primitives in authored styles. For example,
color: var(--color-text)is now used instead ofcolor: var(--color-dark). Primitives (e.g--color-dark: #0d101c) still remain in the codebase, but are now only used to create semantic tokens. They are no longer used directly within style declarations. --width-*properties renamed to more semantic--measure-*to make clear there use is for typographical purposes – setting line length, a.k.a line measure.--tracking-srenamed--tracking-compactinline with other typography related tokens.- Added semantic
--focus-ring-*tokens to allow customisation of focus ring width, color, offset and style. - Added semantic
--text-decoration-*tokens to allow customisation of text decoration color, line, style and thickness. - Added semantic
--stroke-*tokens to allow customisation of style, width and color of borders, outlines, SVG paths etc. - Renamed
--border-radiusto--radiusto make it more widely applicable, particularly when using to modify borderless elements. Also helps prevent confusion as to why most border related properties use--stroke-*, except forborder-radiuswhich used--border-radius. - Rename
--color-bg-*tokens to more semantic--color-canvas(used for main website background) and--color-surface-*, used backgrounds of UI elements. - Introduce semantic
--font-size-*tokens using t-shirt sizing scale. These consume non-semantic type scale primitives (e.g.--step-1). - Added center utility which can be used to horizontally center block-level items.
- Moved region, wrapper and flow from
scss/utilitiestoscss/compositions, as I tend to consider these layout related helpers. and in the boilerplate SCSS, as I tend to consider these layout related helpers. - Moved skip link from
scss/utilitiestoscss/blocks, as I tend to consider this pattern a component.
Documentation website #
- Added theme toggle functionality, allowing site visitors to set their theme preferences whilst reading the docs. Note, this is not part of the cu.css boilerplate as the functionality requires JavaScript to make a theme persists in localStorage. Dark mode in the boilerplate continues to be automatic ”user-preference” only, based on your system settings.
- Added use of ARIA
listrole to remove markers from<ol>’s and<ul>’s. - Split accordion docs into Disclosure Widget and Accordions (a group of disclosure widgets) and added information about how to make accordions accessible.
- Moved region, wrapper and flow from Utilities to Compositions section, as I tend to consider these layout related helpers.
- Moved skip link from Utilities to Blocks section, as I tend to consider this pattern a component.
- Reorganising getting started docs into more logic sections - updating fonts, type and space, and theming.
- Moved documentation site related CSS and JavaScript away from the core boilerplate (
assets/scss) and into its own location (docs/scssanddocs/js). This should prevent confusion as to which code is core and which code is only used in the docs site. - Minor improvements to wording on the homepage.
- Add blockquote render hook for styling callouts.
Bug fixes #
- Added list-style values to remove default
<summary>marker on Safari , see details/summary inconsistencies from Manuel Matuzović for more on this. - Added missing
::selectionstyles andimgfilter to[data-theme="dark"]. Note, this only applies to the documentation website and doesn’t affect the core boilerplate itself.