From ebe5643a8c5166054bc6d5baae8bf682b6f72d35 Mon Sep 17 00:00:00 2001 From: Hans Fast Date: Mon, 2 Mar 2026 10:13:04 +0100 Subject: [PATCH] simplify explanation of versioning; small tweaks to tokens. --- README.md | 12 ++++-------- lib/tokens.yaml | 1 + style.ori.css | 13 +++++++------ token-compute.ori.yaml | 2 +- tokens.yaml | 1 + 5 files changed, 14 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index f19298c..a558c95 100644 --- a/README.md +++ b/README.md @@ -47,22 +47,18 @@ h1 { /*include layout rules: page-layout-grid-centered-#25ea-a0 PINNED */ /*(the angle brackets are needed because the path contains a #)*/ +/*the #VERSION_NUMBER indicates which of the variants in the library is being used. + PINNED is a reminder not to upgrade to a new version without reviewing first. */ ${} - ``` -## Versioning -If a collection of projects are using the shared libary, there might be some divergence of css 'components' used. The idea of the library is that it contains reusable groups of css rules to achieve recognizable outcomes such as 'header', 'menu-to-side-on-mobile', 'sticky-footer', 'content-centered-with-grid', 'content-centered-with-flexbox'. The ideal is to merge improvements from each project into the library in such a way that all projects can benefit, without breaking things. However, sometimes there might be incompatibilities. - -What would work here is a strongly hands-on approach to version control. This is not about isolation of css components; a careful attention to the css cascade in each project is assumed. A solution could be to identify versions of 'solutions' with a unique version number in the name. Demonstrated with `page-laout-grid-centered-#25ea-a0.css`. Additionally, the comment above the include line contains PINNED as a reminder to keep this project on this version until further review; apparently there was a conflict with a newer version of the grid-centered layout css. - ## What about design tokens? This works, too. A `tokens.yaml` file can be read by `tokens.js` and converted to CSS custom property declarations: `titlesize: 3rem` => `--titlesize: 3rem;`. `tokens.js` also optionally merges a default tokens file from `lib` with a local one, overriding default values if they are defined in the local file. -This project contains some convoluted variable overrides for demonstration purposes -- not necessarily recommended in production. +NOTE: This project contains some convoluted variable overrides for demonstration purposes -- not necessarily recommended in production. I suppose Origami templating could be applied to the token files, to compute some values from others? See `./token-compute.ori.yaml`. @@ -71,4 +67,4 @@ I suppose Origami templating could be applied to the token files, to compute som no source mapping makes debugging in the browser more difficult. Could probably be added fairly easily? ## Advantages -no extra tooling and dependencies (e.g. `postcss`) +no extra tooling and dependencies (e.g. `postcss` -- compare [gist-weborigami-postcss](https://git.surfacemarkup.net/hans/gist-weborigami-postcss) diff --git a/lib/tokens.yaml b/lib/tokens.yaml index 07558a5..078cfab 100644 --- a/lib/tokens.yaml +++ b/lib/tokens.yaml @@ -1,3 +1,4 @@ bodycolor: blue +titlecolor: blue titlesize: 3em parspace: 2rem diff --git a/style.ori.css b/style.ori.css index d9b00db..fc7a5d3 100644 --- a/style.ori.css +++ b/style.ori.css @@ -2,21 +2,22 @@ ${tokens.js(tokens.yaml/, lib/tokens.yaml/)} -/*include the typography rules: typography.css*/ +/* include the typography rules: typography.css */ ${lib/typography.css} -/*overrides for typography: typography.css*/ +/* overrides for typography: typography.css */ body { --textcolor: #25c4aa; font-family: 'Jost*', sans-serif; } h1 { + --titlecolor: var(--textcolor); font-size: var(--titlesize) } -/*include layout rules: page-layout-grid-centered-#25ea-a0 PINNED */ -/*(the angle brackets are needed because the path contains a #)*/ +/* include layout rules: page-layout-grid-centered-#25ea-a0 PINNED + * the #VERSION_NUMBER indicates which of the variants in the library is being used. + * PINNED is a reminder not to upgrade to a new version without reviewing first. */ ${} - - +/*(the angle brackets are needed because the path contains a #)*/ diff --git a/token-compute.ori.yaml b/token-compute.ori.yaml index 4461c56..8e2cf0d 100644 --- a/token-compute.ori.yaml +++ b/token-compute.ori.yaml @@ -6,4 +6,4 @@ }._body --- single: ${base} -double: ${base * 2 } +double: ${base * factor } diff --git a/tokens.yaml b/tokens.yaml index 4e7a536..f9db6b4 100644 --- a/tokens.yaml +++ b/tokens.yaml @@ -1 +1,2 @@ bodycolor: red +titlecolor: blue