@thi.ng/meta-css 0.2.0 → 0.4.0

package/README.md

@@ -11,15 +11,9 @@ This project is part of the
 [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo and anti-framework.
 
 - [About](#about)
-  - [Generate CSS frameworks](#generate-css-frameworks)
-  - [Convert meta stylesheets to CSS](#convert-meta-stylesheets-to-css)
-    - [Including custom CSS files](#including-custom-css-files)
-    - [Force inclusion of unreferenced classes](#force-inclusion-of-unreferenced-classes)
-  - [Export](#export)
-    - [Media query variations](#media-query-variations)
-- [Framework generation rules](#framework-generation-rules)
-  - [Overall file structure](#overall-file-structure)
-  - [Example spec](#example-spec)
+- [Generating CSS frameworks](#generating-css-frameworks)
+  - [Framework generation specs & syntax](#framework-generation-specs--syntax)
+  - [Example generation spec](#example-generation-spec)
   - [Spec structure](#spec-structure)
     - [Variations](#variations)
     - [Parametric IDs](#parametric-ids)
@@ -27,6 +21,14 @@ This project is part of the
     - [Properties](#properties)
     - [Key value generation](#key-value-generation)
   - [Media query definitions](#media-query-definitions)
+- [Converting meta stylesheets to CSS](#converting-meta-stylesheets-to-css)
+  - [Meta-stylesheets syntax](#meta-stylesheets-syntax)
+    - [Class identifiers & media query prefixes](#class-identifiers--media-query-prefixes)
+    - [Media query prefixes](#media-query-prefixes)
+  - [Including custom CSS files](#including-custom-css-files)
+  - [Force inclusion of unreferenced classes](#force-inclusion-of-unreferenced-classes)
+- [Exporting a generated framework as CSS](#exporting-a-generated-framework-as-css)
+  - [Media query variations](#media-query-variations)
 - [Bundled CSS base framework](#bundled-css-base-framework)
   - [Classes by category](#classes-by-category)
   - [Media queries](#media-queries)
@@ -35,13 +37,6 @@ This project is part of the
 - [Installation](#installation)
 - [Dependencies](#dependencies)
 - [Usage examples](#usage-examples)
-- [CLI](#cli)
-  - [Basic usage example](#basic-usage-example)
-  - [Generating framework code from bundled base definitions](#generating-framework-code-from-bundled-base-definitions)
-  - [Generating CSS from `.meta` stylesheets](#generating-css-from-meta-stylesheets)
-    - [*.meta stylesheets](#meta-stylesheets)
-    - [Resulting CSS output](#resulting-css-output)
-    - [index.html](#indexhtml)
 - [Authors](#authors)
 - [License](#license)
 
@@ -50,32 +45,41 @@ This project is part of the
 Data-driven CSS framework codegen, transpiler & bundler.
 
 This toolchain and the overall workflow proposed by it is heavily building atop
-the concept of _CSS utility classes_ and how they're utilized (as you might know
-from using Tachyons, Turret or the newer Tailwind projects). How and where those
-CSS classes are applied is however a defining point of difference to other
-existing approaches. This readme aims to provide a thorough overview and some
+the concept of _CSS utility classes_ (as known from Tachyons, Turret or the
+newer Tailwind projects). How and where those CSS classes are applied is however
+a defining point of difference to other existing approaches. Furthermore, using
+JSON as data format for expressing generative rules and as intermediate format
+for generated frameworks, removes the need for any complex CSS-related
+dependencies and makes it trivial to build secondary tooling around (e.g. part
+of this readme is an auto-generated report of the included base framework
+specs).
+
+This readme aims to provide a thorough overview of this toolchain and some
 concrete usage examples...
 
-This package provides a CLI multi-tool to:
+Note: In all cases, final CSS generation itself is handled by
+[thi.ng/hiccup-css](https://github.com/thi-ng/umbrella/blob/develop/packages/hiccup-css/).
+
+**👷🏻 This is all WIP!** Also see included & linked examples for basic usage...
 
-### Generate CSS frameworks
+## Generating CSS frameworks
 
 The `generate` command is used to generate custom frameworks with (likely)
 hundreds of CSS utility classes from a number of extremely compact, parametric
 JSON rule specs. This process generates all desired, combinatorial versions of
 various rules/declarations and exports them to another JSON file used as
-intermediatary for the other commands provided by this toolchain. The
-[syntax/format of the generator rules](#framework-generation-rules) is explained
+intermediary for the other commands provided by this toolchain. The
+[syntax/format of the generator rules](#framework-generation-specs--syntax) is explained
 further on. These rule specs can be split up into multiple files for better
 handling, can define [arbitrary media query criteria]() (all later combinable),
 shared lookup tables for colors, margins, sizes, timings etc.
 
-The package provides generator specs for a basic, fully customizable,
+The package includes generator specs for a basic, fully customizable,
 [tachyons.io](https://tachyons.io)-derived [CSS
 framework](#bundled-css-base-framework). These specs and resulting framework are
-used for some example projects in this repo, but are mainly intended as basic
-starting points for creating other custom frameworks (in the hope they'll be
-shared back similarly)...
+still being worked on and are used for some example projects in this repo, but
+are mostly intended as basic starting points for creating other custom
+frameworks (in the hope they'll be shared back similarly)...
 
 ```text
 metacss generate --help
@@ -93,130 +97,12 @@ Main:
 --prec INT              Number of fractional digits (default: 3)
 ```
 
-### Convert meta stylesheets to CSS
-
-The `convert` command is used to compile & bundle actual CSS from user-provided
-MetaCSS stylesheets (`*.meta` files) and the JSON framework specs created by the
-`generate` command. The meta-stylesheets support any CSS selectors, are nestable
-and compose full CSS declarations from lists of the utility classes in the
-generated framework.
-
-Each item (aka utility class name) can be prefixed with an arbitrary number of
-media query IDs (also custom defined in the framework): e.g. `dark:bg-black`
-might refer to a CSS class to set a black ground, with the `dark:` prefix
-referring to a defined media query which only applies this class when dark mode
-is enabled...
-
-Selectors, declarations and media query criteria will be deduplicated and merged
-from multiple input files. The resulting CSS will only contain referenced rules
-and can be generated in minified or pretty printed formats (it's also possible
-to force include CSS classes which are otherwise unreferenced, using the
-`--force` CLI arg). Additionally, multiple .meta files can be watched for
-changes, their definitions will be merged, and existing CSS files can be
-included (prepended) in the bundled outout too.
-
-```text
-metacss convert --help
-
-Usage: metacss convert [opts] input [...]
-
-Flags:
-
---no-header             Don't emit generated header comment
--p, --pretty            Pretty print output
--v, --verbose           Display extra process information
--w, --watch             Watch input files for changes
-
-Main:
-
---force STR[,..]        [multiple] CSS classes to force include (wildcards are
-                        supported, @-prefix will read from file)
--I STR, --include STR   [multiple] Include CSS files (prepend)
--o STR, --out STR       Output file (or stdout)
--s STR, --specs STR     [required] Path to generated JSON defs
-```
-
-#### Including custom CSS files
-
-One or more existing CSS files can be included & prepended to the output via the
-`--include`/`-I` arg (which can be given multiple times). These files are used
-verbatim and will **not** be transformed or reformatted in any way.
-
-#### Force inclusion of unreferenced classes
-
-Only the CSS classes (and their optionally associated media queries) referenced
-in a `.meta` stylesheet will appear in the export CSS bundle. This ensures that
-the resulting CSS will only contain what's actually used (same effect as
-tree-shaking, only vastly more efficient). However, this also means any CSS
-classes (and optionally, their media query qualifiers) which are otherwise
-referenced (e.g. from JS/TS source code or HTML docs) **will not** be included
-by default and they will need to be listed manually for forced inclusion.
-
-This can be achieved via the `--force`/`-f` arg (also can be given multiple
-times). This option also supports basic `*`-wildcard patterns, e.g. `bg-*` to
-include all classes with prefix `bg-`. Furthermore, for larger projects it's
-useful to store these names/patterns in a separate file. For that purpose, use
-the `@` prefix (e.g. `-f @includes.txt`) to indicate reading from file (only
-reading from a single file is supported at current)... See the [meta-css-basics
-example
-project](https://github.com/thi-ng/umbrella/blob/develop/examples/meta-css-basics)
-for concrete usage...
-
-### Export
-
-The `export` command is intended for those who're mainly interested in the CSS
-framework generation aspects of this toolchain. This command merely takes an
-existing generated framework JSON file and serializes it to a single CSS file,
-e.g. to be then used with other CSS tooling (e.g. `postcss`).
-
-#### Media query variations
-
-Users can choose to generate variations of all defined utility classes for any
-of the framework-defined media query IDs. This will create additional suffixed
-versions of all classes (with their appropriate media query wrappers) and cause
-a potentially massive output (depending on the overall number/complexity of the
-generated classes). Again, the idea is that the resulting CSS file will be
-post-processed with 3rd party CSS tooling...
-
-For example, if the framework contains a CSS class `w-50` (e.g. to set the width
-to 50%) and media queries for different screen sizes (e.g. named `ns`, `l`),
-then the export with said media queries will also generate classes `w-50-ns`
-and `w-50-l` (incl. their corresponding `@media` wrappers).
-
-As with the `convert` command, additional CSS files can also be included
-(prepended) in the output file.
-
-```text
-metacss export --help
-
-Usage: metacss export [opts] input
-
-Flags:
-
---no-header             Don't emit generated header comment
--p, --pretty            Pretty print output
--v, --verbose           Display extra process information
-
-Main:
-
--I STR, --include STR   [multiple] Include CSS files (prepend)
--m STR, --media STR     Media query IDs (use 'ALL' for all)
--o STR, --out STR       Output file (or stdout)
-```
-
-Note: In all cases, final CSS generation itself is handled by
-[thi.ng/hiccup-css](https://github.com/thi-ng/umbrella/blob/develop/packages/hiccup-css/)
-
-**👷🏻 This is all WIP!** See example below for basic example usage...
-
-## Framework generation rules
+### Framework generation specs & syntax
 
 This section gives an overview of the JSON format used to generate CSS
 frameworks of dozens (usually hundreds) of utility classes, including many
 possible variations (per spec).
 
-### Overall file structure
-
 Generation specs use a simple JSON structure as shown below. The specs can be
 split over multiple files within a directory and will all be merged by the
 `generate` command of the toolchain.
@@ -228,15 +114,25 @@ split over multiple files within a directory and will all be merged by the
         "name": "Framework name",
         "version": "0.0.0",
     },
-    // optional media queries and their criteria
+    // optional media queries and their criteria, will be merged from multiple spec files
     "media": {
         "large": { "min-width": "60rem" },
         "dark": { "prefers-color-scheme": "dark" }
     },
     // optional shared values/LUTs (arrays or objects)
+    // tables are always local to the current spec file only...
     "tables": {
         "margins": [0, 0.25, 0.5, 1, 2, 4]
     },
+    // optional shared variations
+    "vars": {
+        "size": ["width", "height"]
+    },
+    // optional thi.ng/hiccup-css declarations which will be part of the framework
+    // (e.g. for CSS reset purposes), will be merged from multiple spec files
+    "decls": [
+        ["html", { "box-sizing": "border-box" }]
+    ],
     // array of actual generation specs
     "specs": [
         //...
@@ -244,7 +140,7 @@ split over multiple files within a directory and will all be merged by the
 }
 ```
 
-### Example spec
+### Example generation spec
 
 The following generator document uses a single small generative rule spec to
 create altogether 21 utility classes for various possible margins (where 21 = 3
@@ -336,8 +232,8 @@ An individual generator spec JSON object can contain the following keys:
 | `var`    | string[], optional      | Array of variation IDs (see section below)                   |
 | `user`   | any, optional           | Custom user data, comments, metadata etc.                    |
 
-The number of generated CSS classes per spec is number of items in `values`
-multiplied with the number of variations in `var` (if any).
+The number of generated CSS classes per spec is the number of items in `values`
+multiplied by the number of variations in `var` (if any).
 
 Any `user` data will be stored (as is) with each generated CSS class, but
 currently has no other direct use in the toolchain and is meant for additional
@@ -517,98 +413,453 @@ ALWAYS combined using `and`:
 See [media queries in the bundled base
 specs](https://github.com/thi-ng/umbrella/blob/982fff7bfcc48f108b6ad88f854ef00be4078510/packages/meta-css/specs/_info.json#L6-L24)
 
-## Bundled CSS base framework
+## Converting meta stylesheets to CSS
 
-The package includes a large number of useful specs in [/specs](https://github.com/thi-ng/umbrella/blob/develop/packages/meta-css/specs/). These are provided as starting point to define your custom framework(s)...
+The `convert` command is used to compile & bundle actual CSS from user-provided
+MetaCSS stylesheets (`*.meta` files) and the JSON framework specs created by the
+`generate` command. The meta-stylesheets support any CSS selectors, are nestable
+and compose full CSS declarations from lists of the utility classes in the
+generated framework.
 
-Currently available CSS classes in MetaCSS base v0.0.1:
+Each item (aka utility class name) can be prefixed with an arbitrary number of
+media query IDs (also custom defined in the framework): e.g. `dark:bg-black`
+might refer to a CSS class to set a black ground, with the `dark:` prefix
+referring to a defined media query which only applies this class when dark mode
+is enabled...
 
-### Classes by category
+Selectors, declarations and media query criteria will be deduplicated and merged
+from multiple input files. **The resulting CSS will only contain referenced
+rules** and can be generated in minified or pretty printed formats (it's also
+possible to [force include CSS classes which are otherwise
+unreferenced](#force-inclusion-of-unreferenced-classes)). Additionally, multiple
+`.meta` stylesheets can be watched for changes (their definitions getting
+merged), and existing CSS files can be included (prepended) in the bundled
+output too.
 
-#### Animations / transitions <!-- notoc -->
+```text
+metacss convert --help
 
-`bg-anim1` / `bg-anim2` / `bg-anim3`
+Usage: metacss convert [opts] input [...]
 
-#### Border radius <!-- notoc -->
+Flags:
 
-`br0` / `br1` / `br2` / `br3` / `br4` / `brb0` / `brb1` / `brb2` / `brb3` / `brb4` / `brl0` / `brl1` / `brl2` / `brl3` / `brl4` / `brr0` / `brr1` / `brr2` / `brr3` / `brr4` / `brt0` / `brt1` / `brt2` / `brt3` / `brt4`
+-d, --no-decls          Don't emit framework decls
+--no-header             Don't emit generated header comment
+-p, --pretty            Pretty print output
+-v, --verbose           Display extra process information
+-w, --watch             Watch input files for changes
 
-#### Border width <!-- notoc -->
+Main:
 
-`bw0` / `bw1` / `bw2` / `bw3` / `bw4` / `bw5` / `bwb0` / `bwb1` / `bwb2` / `bwb3` / `bwb4` / `bwb5` / `bwl0` / `bwl1` / `bwl2` / `bwl3` / `bwl4` / `bwl5` / `bwr0` / `bwr1` / `bwr2` / `bwr3` / `bwr4` / `bwr5` / `bwt0` / `bwt1` / `bwt2` / `bwt3` / `bwt4` / `bwt5`
+-e STR, --eval STR      eval meta stylesheet in given string (ignores other
+                        inputs & includes)
+-f STR, --force STR     [multiple] CSS classes to force include (wildcards are
+                        supported, @-prefix will read from file)
+-I STR, --include STR   [multiple] Include CSS files (prepend)
+-o STR, --out STR       Output file (or stdout)
+-s STR, --specs STR     [required] Path to generated JSON defs
+```
 
-#### Colors <!-- notoc -->
+### Meta-stylesheets syntax
 
-`b--black` / `b--blue` / `b--dark-blue` / `b--dark-gray` / `b--dark-green` / `b--dark-pink` / `b--dark-red` / `b--gold` / `b--gray` / `b--green` / `b--hot-pink` / `b--light-blue` / `b--light-gray` / `b--light-green` / `b--light-pink` / `b--light-purple` / `b--light-red` / `b--light-silver` / `b--light-yellow` / `b--lightest-blue` / `b--mid-gray` / `b--moon-gray` / `b--navy` / `b--near-black` / `b--near-white` / `b--orange` / `b--pink` / `b--purple` / `b--red` / `b--silver` / `b--transparent` / `b--vcol1` / `b--vcol10` / `b--vcol11` / `b--vcol12` / `b--vcol13` / `b--vcol14` / `b--vcol15` / `b--vcol16` / `b--vcol2` / `b--vcol3` / `b--vcol4` / `b--vcol5` / `b--vcol6` / `b--vcol7` / `b--vcol8` / `b--vcol9` / `b--washed-blue` / `b--washed-green` / `b--washed-red` / `b--washed-yellow` / `b--white` / `b--yellow` / `bg-black` / `bg-blue` / `bg-dark-blue` / `bg-dark-gray` / `bg-dark-green` / `bg-dark-pink` / `bg-dark-red` / `bg-gold` / `bg-gray` / `bg-green` / `bg-hot-pink` / `bg-light-blue` / `bg-light-gray` / `bg-light-green` / `bg-light-pink` / `bg-light-purple` / `bg-light-red` / `bg-light-silver` / `bg-light-yellow` / `bg-lightest-blue` / `bg-mid-gray` / `bg-moon-gray` / `bg-navy` / `bg-near-black` / `bg-near-white` / `bg-orange` / `bg-pink` / `bg-purple` / `bg-red` / `bg-silver` / `bg-transparent` / `bg-vcol1` / `bg-vcol10` / `bg-vcol11` / `bg-vcol12` / `bg-vcol13` / `bg-vcol14` / `bg-vcol15` / `bg-vcol16` / `bg-vcol2` / `bg-vcol3` / `bg-vcol4` / `bg-vcol5` / `bg-vcol6` / `bg-vcol7` / `bg-vcol8` / `bg-vcol9` / `bg-washed-blue` / `bg-washed-green` / `bg-washed-red` / `bg-washed-yellow` / `bg-white` / `bg-yellow` / `black` / `blue` / `dark-blue` / `dark-gray` / `dark-green` / `dark-pink` / `dark-red` / `gold` / `gray` / `green` / `hot-pink` / `light-blue` / `light-gray` / `light-green` / `light-pink` / `light-purple` / `light-red` / `light-silver` / `light-yellow` / `lightest-blue` / `mid-gray` / `moon-gray` / `navy` / `near-black` / `near-white` / `o-0` / `o-10` / `o-100` / `o-20` / `o-30` / `o-40` / `o-50` / `o-60` / `o-70` / `o-80` / `o-90` / `orange` / `pink` / `purple` / `red` / `silver` / `transparent` / `vcol1` / `vcol10` / `vcol11` / `vcol12` / `vcol13` / `vcol14` / `vcol15` / `vcol16` / `vcol2` / `vcol3` / `vcol4` / `vcol5` / `vcol6` / `vcol7` / `vcol8` / `vcol9` / `washed-blue` / `washed-green` / `washed-red` / `washed-yellow` / `white` / `yellow`
+As mentioned earlier, the `convert` command transpiles meta-stylesheets into
+actual CSS. These stylesheets support any CSS selector, support selector
+nesting and have the following basic syntax:
 
-#### Cursors <!-- notoc -->
+```text
+// line comment
+selector {
+  class-id1 class-id2 ...
+  {
+    nested-selector {
+      class-id3 ...
+      {
+        ...
+      }
+    }
+  }
+}
+```
 
-`cursor-alias` / `cursor-auto` / `cursor-cell` / `cursor-col` / `cursor-context` / `cursor-copy` / `cursor-cross` / `cursor-default` / `cursor-e` / `cursor-ew` / `cursor-forbidden` / `cursor-grab` / `cursor-grabbing` / `cursor-help` / `cursor-in` / `cursor-move` / `cursor-n` / `cursor-ne` / `cursor-news` / `cursor-no-drop` / `cursor-none` / `cursor-ns` / `cursor-nw` / `cursor-nwse` / `cursor-out` / `cursor-pointer` / `cursor-progress` / `cursor-row` / `cursor-s` / `cursor-scroll` / `cursor-se` / `cursor-sw` / `cursor-text` / `cursor-vtext` / `cursor-w` / `cursor-wait`
+#### Class identifiers & media query prefixes
 
-#### Width <!-- notoc -->
+As indicated by the above file structure, `*.meta` stylesheets purely consist of
+CSS selectors and the names of the generated framework-defined utility classes.
+For example, using the [bundled framework specs](#bundled-css-base-framework),
+this simple meta-stylesheet `body { ma0 monospace blue }` creates a CSS rule for
+`body` with the definitions of the generated `ma0`, `monospace` and `blue`
+classes inline-expanded:
 
-`w-10` / `w-100` / `w-20` / `w-25` / `w-30` / `w-33` / `w-34` / `w-40` / `w-50` / `w-60` / `w-66` / `w-70` / `w-75` / `w-80` / `w-90` / `w1` / `w2` / `w3` / `w4` / `w5`
+```css
+body {
+    margin: 0rem;
+    font-family: Monaco, Menlo, Consolas, 'Courier New', monospace;
+    color: #357edd;
+}
+```
 
-#### Max. width <!-- notoc -->
+#### Media query prefixes
 
-`mw-10` / `mw-100` / `mw-20` / `mw-25` / `mw-30` / `mw-33` / `mw-34` / `mw-40` / `mw-50` / `mw-60` / `mw-66` / `mw-70` / `mw-75` / `mw-80` / `mw-90` / `mw1` / `mw2` / `mw3` / `mw4` / `mw5`
+This toolchain doesn't pre-generate media-query-specific versions of any CSS
+class, and any class ID/token can be prefixed with any number of media query IDs
+(separated by `:`). These [media queries are defined as part of the framework
+generation specs](#media-query-definitions) and when used as a prefix, multiple
+query IDs can be combined freely. For example, the meta-stylesheet `a:hover {
+dark:bg-blue dark:anim:bg-anim2 }` will auto-create two separate CSS
+`@media`-query blocks for the query IDs `dark` and `(dark AND anim)`:
 
-#### Height <!-- notoc -->
+```css
+@media (prefers-color-scheme: dark) {
+    a:hover {
+        background-color: #357edd;
+    }
+}
 
-`h-10` / `h-100` / `h-20` / `h-25` / `h-30` / `h-33` / `h-34` / `h-40` / `h-50` / `h-60` / `h-66` / `h-70` / `h-75` / `h-80` / `h-90` / `h1` / `h2` / `h3` / `h4` / `h5`
+@media (prefers-color-scheme: dark) and (not (prefers-reduced-motion)) {
+    a:hover {
+        transition: 0.25s background-color ease-in-out;
+    }
+}
+```
 
-#### Display mode <!-- notoc -->
+A more detailed example, split over two files (for merging & bundling):
 
-`db` / `df` / `dg` / `di` / `dib` / `dif` / `dig` / `dn` / `dt` / `dtc` / `dtr`
+readme.meta:
 
-#### Grid layout <!-- notoc -->
+```text tangle:export/readme.meta
+body {
+    // no margins
+    ma0
+    // default colors
+    bg-white black
+    // colors for dark mode
+    dark:bg-black dark:white
+}
 
-`gap0` / `gap1` / `gap2` / `gap3` / `gap4` / `gap5` / `gc1` / `gc10` / `gc2` / `gc3` / `gc4` / `gc5` / `gc6` / `gc7` / `gc8` / `gc9` / `gr1` / `gr10` / `gr2` / `gr3` / `gr4` / `gr5` / `gr6` / `gr7` / `gr8` / `gr9`
+#app { ma3 }
 
-#### Lists <!-- notoc -->
+.bt-group-v > a {
+    db w-100 l:w-50 ph3 pv2 bwb1
+    dark:bg-purple dark:white dark:b--black
+    light:bg-light-blue light:black light:b--white
 
-`list`
+    // nested selectors
+    {
+        :hover { bg-gold black anim:bg-anim2 }
+        :first-child { brt3 }
+        :last-child { brb3 bwb0 }
+    }
+}
+```
 
-#### Padding <!-- notoc -->
+readme2.meta:
 
-`pa0` / `pa1` / `pa2` / `pa3` / `pa4` / `pb0` / `pb1` / `pb2` / `pb3` / `pb4` / `ph0` / `ph1` / `ph2` / `ph3` / `ph4` / `pl0` / `pl1` / `pl2` / `pl3` / `pl4` / `pr0` / `pr1` / `pr2` / `pr3` / `pr4` / `pt0` / `pt1` / `pt2` / `pt3` / `pt4` / `pv0` / `pv1` / `pv2` / `pv3` / `pv4`
+We will merge the definitions in this file with the ones above (i.e. adding &
+overriding some of the declarations, here: a larger border radius):
 
-#### Margin <!-- notoc -->
+```text tangle:export/readme2.meta
+#app { pa2 }
 
-`center` / `ma0` / `ma1` / `ma2` / `ma3` / `ma4` / `mb0` / `mb1` / `mb2` / `mb3` / `mb4` / `mh0` / `mh1` / `mh2` / `mh3` / `mh4` / `ml0` / `ml1` / `ml2` / `ml3` / `ml4` / `mr0` / `mr1` / `mr2` / `mr3` / `mr4` / `mt0` / `mt1` / `mt2` / `mt3` / `mt4` / `mv0` / `mv1` / `mv2` / `mv3` / `mv4`
+.bt-group-v > a {
+    {
+        :first-child { brt4 }
+        :last-child { brb4 }
+    }
+}
+```
 
-#### Overflow <!-- notoc -->
+```bash
+# if no --out dir is specified, writes result to stdout...
+# use previously generated framework for resolving all identifiers & media queries
+metacss convert --pretty --specs framework.json readme.meta readme2.meta
+```
 
-`overflow-auto` / `overflow-hidden` / `overflow-scroll` / `overflow-visible` / `overflow-x-auto` / `overflow-x-hidden` / `overflow-x-scroll` / `overflow-x-visible` / `overflow-y-auto` / `overflow-y-hidden` / `overflow-y-scroll` / `overflow-y-visible`
+Resulting CSS bundle output:
 
-#### Positions <!-- notoc -->
+```css
+/*! MetaCSS base v0.0.1 - generated by thi.ng/meta-css @ 2023-12-18T12:22:36.548Z */
+body {
+    margin: 0rem;
+    background-color: #fff;
+    color: #000;
+}
 
-`absolute` / `bottom--1` / `bottom--2` / `bottom-0` / `bottom-1` / `bottom-2` / `fixed` / `left--1` / `left--2` / `left-0` / `left-1` / `left-2` / `relative` / `right--1` / `right--2` / `right-0` / `right-1` / `right-2` / `sticky` / `top--1` / `top--2` / `top-0` / `top-1` / `top-2`
+#app {
+    margin: 1rem;
+    padding: .5rem;
+}
 
-#### Z-indices <!-- notoc -->
+.bt-group-v > a {
+    display: block;
+    width: 100%;
+    padding-left: 1rem;
+    padding-right: 1rem;
+    padding-top: .5rem;
+    padding-bottom: .5rem;
+    border-bottom-style: solid;
+    border-bottom-width: .125rem;
+}
 
-`z-0` / `z-1` / `z-2` / `z-3` / `z-4` / `z-5` / `z-999` / `z-9999`
+.bt-group-v > a:hover {
+    background-color: #ffb700;
+    color: #000;
+}
 
-#### Shadow <!-- notoc -->
+.bt-group-v > a:first-child {
+    border-top-left-radius: 1rem;
+    border-top-right-radius: 1rem;
+}
 
-`i-shadow-1` / `i-shadow-2` / `i-shadow-3` / `i-shadow-4` / `shadow-1` / `shadow-2` / `shadow-3` / `shadow-4`
+.bt-group-v > a:last-child {
+    border-bottom-left-radius: 1rem;
+    border-bottom-right-radius: 1rem;
+    border-bottom-style: solid;
+    border-bottom-width: 0rem;
+}
 
-#### Font families <!-- notoc -->
+@media (prefers-color-scheme:dark) {
 
-`monospace` / `sans-serif` / `serif` / `system`
+    body {
+        background-color: #000;
+        color: #fff;
+    }
 
-#### Font sizes <!-- notoc -->
+    .bt-group-v > a {
+        background-color: #5e2ca5;
+        color: #fff;
+        border-color: #000;
+    }
 
-`f-subtitle` / `f-title` / `f1` / `f2` / `f3` / `f4` / `f5` / `f6` / `f7`
+}
 
-#### Font weights <!-- notoc -->
+@media (min-width:60rem) {
 
-`b` / `fw100` / `fw200` / `fw300` / `fw400` / `fw500` / `fw600` / `fw700` / `fw800` / `fw900` / `normal`
+    .bt-group-v > a {
+        width: 50%;
+    }
+
+}
+
+@media (prefers-color-scheme:light) {
+
+    .bt-group-v > a {
+        background-color: #96ccff;
+        color: #000;
+        border-color: #fff;
+    }
+
+}
+
+@media not (prefers-reduced-motion) {
+
+    .bt-group-v > a:hover {
+        transition: 0.2s background-color ease-in-out;
+    }
+
+}
+```
+
+### Including custom CSS files
+
+One or more existing CSS files can be included & prepended to the output via the
+`--include`/`-I` arg (which can be given multiple times). These files are used
+verbatim and will **not** be transformed or reformatted in any way.
+
+### Force inclusion of unreferenced classes
+
+Only the CSS classes (and their optionally associated media queries) referenced
+in a `.meta` stylesheet will appear in the export CSS bundle. This ensures that
+the resulting CSS will only contain what's actually used (same effect as
+tree-shaking, only vastly more efficient). However, this also means any CSS
+classes (and optionally, their media query qualifiers) which are otherwise
+referenced (e.g. from JS/TS source code or HTML docs) **will not** be included
+by default and they will need to be listed manually for forced inclusion.
+
+This can be achieved via the `--force`/`-f` arg (also can be given multiple
+times). This option also supports basic `*`-wildcard patterns, e.g. `bg-*` to
+include all classes with prefix `bg-`. Furthermore, for larger projects it's
+useful to store these names/patterns in a separate file. For that purpose, use
+the `@` prefix (e.g. `-f @includes.txt`) to indicate reading from file (only
+reading from a single file is supported at current)... See the [meta-css-basics
+example
+project](https://github.com/thi-ng/umbrella/blob/develop/examples/meta-css-basics)
+for concrete usage...
+
+## Exporting a generated framework as CSS
+
+The `export` command is intended for those who're mainly interested in the CSS
+framework generation aspects of this toolchain. This command merely takes an
+existing generated framework JSON file and serializes it to a single CSS file,
+e.g. to be then used with other CSS tooling (e.g. `postcss`).
+
+### Media query variations
+
+Users can choose to generate variations of all defined utility classes for any
+of the framework-defined media query IDs. This will create additional suffixed
+versions of all classes (with their appropriate media query wrappers) and cause
+a potentially massive output (depending on the overall number/complexity of the
+generated classes). Again, the idea is that the resulting CSS file will be
+post-processed with 3rd party CSS tooling...
+
+For example, if the framework contains a CSS class `w-50` (e.g. to set the width
+to 50%) and media queries for different screen sizes (e.g. named `ns`, `l`),
+then the export with said media queries will also generate classes `w-50-ns`
+and `w-50-l` (incl. their corresponding `@media` wrappers).
+
+As with the `convert` command, additional CSS files can also be included
+(prepended) in the output file.
+
+```text
+metacss export --help
+
+Usage: metacss export [opts] input
+
+Flags:
+
+-d, --no-decls          Don't emit framework decls
+--no-header             Don't emit generated header comment
+-p, --pretty            Pretty print output
+-v, --verbose           Display extra process information
+
+Main:
+
+-I STR, --include STR   [multiple] Include CSS files (prepend)
+-m ID, --media ID       [multiple] Media query IDs (use 'ALL' for all)
+-o STR, --out STR       Output file (or stdout)
+```
+
+## Bundled CSS base framework
+
+The package includes a large number of useful specs in [/specs](https://github.com/thi-ng/umbrella/blob/develop/packages/meta-css/specs/). These are provided as starting point to define your custom framework(s)...
+
+Currently available CSS classes in MetaCSS base v0.0.1:
+
+### Classes by category
+
+#### Accessibility <!-- notoc -->
+
+`screen-reader` / `screen-reader-focus`
+
+#### Animations / transitions <!-- notoc -->
+
+`bg-anim1` / `bg-anim2` / `bg-anim3`
+
+#### Aspect ratios <!-- notoc -->
+
+`aspect-ratio-16x9` / `aspect-ratio-1x1` / `aspect-ratio-3x4` / `aspect-ratio-4x3` / `aspect-ratio-4x6` / `aspect-ratio-6x4` / `aspect-ratio-9x16` / `aspect-ratio-object`
+
+#### Background <!-- notoc -->
+
+`bg-contain` / `bg-cover` / `bg-pos-center` / `bg-pos-e` / `bg-pos-n` / `bg-pos-ne` / `bg-pos-nw` / `bg-pos-s` / `bg-pos-se` / `bg-pos-sw` / `bg-pos-w`
+
+#### Border radius <!-- notoc -->
+
+`br-100` / `br-pill` / `br0` / `br1` / `br2` / `br3` / `br4` / `brb0` / `brb1` / `brb2` / `brb3` / `brb4` / `brl0` / `brl1` / `brl2` / `brl3` / `brl4` / `brr0` / `brr1` / `brr2` / `brr3` / `brr4` / `brt0` / `brt1` / `brt2` / `brt3` / `brt4`
+
+#### Border width <!-- notoc -->
+
+`bw-1px` / `bw0` / `bw1` / `bw2` / `bw3` / `bw4` / `bw5` / `bwb-1px` / `bwb0` / `bwb1` / `bwb2` / `bwb3` / `bwb4` / `bwb5` / `bwl-1px` / `bwl0` / `bwl1` / `bwl2` / `bwl3` / `bwl4` / `bwl5` / `bwr-1px` / `bwr0` / `bwr1` / `bwr2` / `bwr3` / `bwr4` / `bwr5` / `bwt-1px` / `bwt0` / `bwt1` / `bwt2` / `bwt3` / `bwt4` / `bwt5`
+
+#### Colors <!-- notoc -->
+
+`b--black` / `b--blue` / `b--dark-blue` / `b--dark-gray` / `b--dark-green` / `b--dark-pink` / `b--dark-red` / `b--gold` / `b--gray` / `b--green` / `b--hot-pink` / `b--light-blue` / `b--light-gray` / `b--light-green` / `b--light-pink` / `b--light-purple` / `b--light-red` / `b--light-silver` / `b--light-yellow` / `b--lightest-blue` / `b--mid-gray` / `b--moon-gray` / `b--navy` / `b--near-black` / `b--near-white` / `b--orange` / `b--pink` / `b--purple` / `b--red` / `b--silver` / `b--transparent` / `b--vcol1` / `b--vcol10` / `b--vcol11` / `b--vcol12` / `b--vcol13` / `b--vcol14` / `b--vcol15` / `b--vcol16` / `b--vcol2` / `b--vcol3` / `b--vcol4` / `b--vcol5` / `b--vcol6` / `b--vcol7` / `b--vcol8` / `b--vcol9` / `b--washed-blue` / `b--washed-green` / `b--washed-red` / `b--washed-yellow` / `b--white` / `b--yellow` / `bg-black` / `bg-blue` / `bg-dark-blue` / `bg-dark-gray` / `bg-dark-green` / `bg-dark-pink` / `bg-dark-red` / `bg-gold` / `bg-gray` / `bg-green` / `bg-hot-pink` / `bg-light-blue` / `bg-light-gray` / `bg-light-green` / `bg-light-pink` / `bg-light-purple` / `bg-light-red` / `bg-light-silver` / `bg-light-yellow` / `bg-lightest-blue` / `bg-mid-gray` / `bg-moon-gray` / `bg-navy` / `bg-near-black` / `bg-near-white` / `bg-orange` / `bg-pink` / `bg-purple` / `bg-red` / `bg-silver` / `bg-transparent` / `bg-vcol1` / `bg-vcol10` / `bg-vcol11` / `bg-vcol12` / `bg-vcol13` / `bg-vcol14` / `bg-vcol15` / `bg-vcol16` / `bg-vcol2` / `bg-vcol3` / `bg-vcol4` / `bg-vcol5` / `bg-vcol6` / `bg-vcol7` / `bg-vcol8` / `bg-vcol9` / `bg-washed-blue` / `bg-washed-green` / `bg-washed-red` / `bg-washed-yellow` / `bg-white` / `bg-yellow` / `black` / `blue` / `dark-blue` / `dark-gray` / `dark-green` / `dark-pink` / `dark-red` / `gold` / `gray` / `green` / `hot-pink` / `light-blue` / `light-gray` / `light-green` / `light-pink` / `light-purple` / `light-red` / `light-silver` / `light-yellow` / `lightest-blue` / `mid-gray` / `moon-gray` / `navy` / `near-black` / `near-white` / `o-0` / `o-10` / `o-100` / `o-20` / `o-30` / `o-40` / `o-50` / `o-60` / `o-70` / `o-80` / `o-90` / `orange` / `pink` / `purple` / `red` / `silver` / `transparent` / `vcol1` / `vcol10` / `vcol11` / `vcol12` / `vcol13` / `vcol14` / `vcol15` / `vcol16` / `vcol2` / `vcol3` / `vcol4` / `vcol5` / `vcol6` / `vcol7` / `vcol8` / `vcol9` / `washed-blue` / `washed-green` / `washed-red` / `washed-yellow` / `white` / `yellow`
+
+#### Cursors <!-- notoc -->
+
+`cursor-alias` / `cursor-auto` / `cursor-cell` / `cursor-col` / `cursor-context` / `cursor-copy` / `cursor-cross` / `cursor-default` / `cursor-e` / `cursor-ew` / `cursor-forbidden` / `cursor-grab` / `cursor-grabbing` / `cursor-help` / `cursor-in` / `cursor-move` / `cursor-n` / `cursor-ne` / `cursor-news` / `cursor-no-drop` / `cursor-none` / `cursor-ns` / `cursor-nw` / `cursor-nwse` / `cursor-out` / `cursor-pointer` / `cursor-progress` / `cursor-row` / `cursor-s` / `cursor-scroll` / `cursor-se` / `cursor-sw` / `cursor-text` / `cursor-vtext` / `cursor-w` / `cursor-wait`
+
+#### Display mode <!-- notoc -->
+
+`db` / `df` / `dg` / `di` / `dib` / `dif` / `dig` / `dn` / `dt` / `dtc` / `dtr`
+
+#### Font families <!-- notoc -->
+
+`monospace` / `sans-serif` / `serif` / `system` / `system-sans-serif` / `system-serif`
+
+#### Font sizes <!-- notoc -->
+
+`f-subtitle` / `f-title` / `f1` / `f2` / `f3` / `f4` / `f5` / `f6` / `f7`
+
+#### Font style <!-- notoc -->
+
+`italic`
 
 #### Font variants <!-- notoc -->
 
 `small-caps`
 
+#### Font weights <!-- notoc -->
+
+`b` / `fw100` / `fw200` / `fw300` / `fw400` / `fw500` / `fw600` / `fw700` / `fw800` / `fw900` / `normal`
+
+#### Grid layout <!-- notoc -->
+
+`align-items-center` / `align-items-end` / `align-items-start` / `align-items-stretch` / `align-self-center` / `align-self-end` / `align-self-start` / `align-self-stretch` / `gap-1px` / `gap-2px` / `gap-4px` / `gap-8px` / `gap0` / `gap1` / `gap2` / `gap3` / `gap4` / `gap5` / `grid-cols-1` / `grid-cols-10` / `grid-cols-2` / `grid-cols-3` / `grid-cols-4` / `grid-cols-5` / `grid-cols-6` / `grid-cols-7` / `grid-cols-8` / `grid-cols-9` / `grid-rows-1` / `grid-rows-10` / `grid-rows-2` / `grid-rows-3` / `grid-rows-4` / `grid-rows-5` / `grid-rows-6` / `grid-rows-7` / `grid-rows-8` / `grid-rows-9` / `justify-items-center` / `justify-items-end` / `justify-items-start` / `justify-items-stretch` / `justify-self-center` / `justify-self-end` / `justify-self-start` / `justify-self-stretch`
+
+#### Height <!-- notoc -->
+
+`h-10` / `h-100` / `h-16` / `h-17` / `h-20` / `h-25` / `h-30` / `h-33` / `h-34` / `h-40` / `h-50` / `h-60` / `h-66` / `h-67` / `h-70` / `h-75` / `h-80` / `h-83` / `h-84` / `h-90` / `h1` / `h2` / `h3` / `h4` / `h5`
+
+#### Icons <!-- notoc -->
+
+`icon-1` / `icon-2` / `icon-3` / `icon-4` / `icon-5` / `icon-6` / `icon-7` / `icon-subtitle` / `icon-title`
+
+#### Letter spacing <!-- notoc -->
+
+`ls--1` / `ls--2` / `ls-0` / `ls-1` / `ls-2` / `ls-3`
+
+#### Line heights <!-- notoc -->
+
+`lh-0` / `lh-copy` / `lh-double` / `lh-solid` / `lh-title`
+
+#### Lists <!-- notoc -->
+
+`list`
+
+#### Margin <!-- notoc -->
+
+`center` / `ma0` / `ma1` / `ma2` / `ma3` / `ma4` / `mb0` / `mb1` / `mb2` / `mb3` / `mb4` / `mh0` / `mh1` / `mh2` / `mh3` / `mh4` / `ml0` / `ml1` / `ml2` / `ml3` / `ml4` / `mr0` / `mr1` / `mr2` / `mr3` / `mr4` / `mt0` / `mt1` / `mt2` / `mt3` / `mt4` / `mv0` / `mv1` / `mv2` / `mv3` / `mv4`
+
+#### Max. height <!-- notoc -->
+
+`maxh-10` / `maxh-100` / `maxh-16` / `maxh-17` / `maxh-20` / `maxh-25` / `maxh-30` / `maxh-33` / `maxh-34` / `maxh-40` / `maxh-50` / `maxh-60` / `maxh-66` / `maxh-67` / `maxh-70` / `maxh-75` / `maxh-80` / `maxh-83` / `maxh-84` / `maxh-90` / `maxh1` / `maxh2` / `maxh3` / `maxh4` / `maxh5`
+
+#### Max. width <!-- notoc -->
+
+`maxw-10` / `maxw-100` / `maxw-16` / `maxw-17` / `maxw-20` / `maxw-25` / `maxw-30` / `maxw-33` / `maxw-34` / `maxw-40` / `maxw-50` / `maxw-60` / `maxw-66` / `maxw-67` / `maxw-70` / `maxw-75` / `maxw-80` / `maxw-83` / `maxw-84` / `maxw-90` / `maxw1` / `maxw2` / `maxw3` / `maxw4` / `maxw5`
+
+#### Min. height <!-- notoc -->
+
+`minh-10` / `minh-100` / `minh-16` / `minh-17` / `minh-20` / `minh-25` / `minh-30` / `minh-33` / `minh-34` / `minh-40` / `minh-50` / `minh-60` / `minh-66` / `minh-67` / `minh-70` / `minh-75` / `minh-80` / `minh-83` / `minh-84` / `minh-90` / `minh1` / `minh2` / `minh3` / `minh4` / `minh5`
+
+#### Min. width <!-- notoc -->
+
+`minw-10` / `minw-100` / `minw-16` / `minw-17` / `minw-20` / `minw-25` / `minw-30` / `minw-33` / `minw-34` / `minw-40` / `minw-50` / `minw-60` / `minw-66` / `minw-67` / `minw-70` / `minw-75` / `minw-80` / `minw-83` / `minw-84` / `minw-90` / `minw1` / `minw2` / `minw3` / `minw4` / `minw5`
+
+#### Overflow <!-- notoc -->
+
+`overflow-auto` / `overflow-hidden` / `overflow-scroll` / `overflow-visible` / `overflow-x-auto` / `overflow-x-hidden` / `overflow-x-scroll` / `overflow-x-visible` / `overflow-y-auto` / `overflow-y-hidden` / `overflow-y-scroll` / `overflow-y-visible`
+
+#### Padding <!-- notoc -->
+
+`pa0` / `pa1` / `pa2` / `pa3` / `pa4` / `pb0` / `pb1` / `pb2` / `pb3` / `pb4` / `ph0` / `ph1` / `ph2` / `ph3` / `ph4` / `pl0` / `pl1` / `pl2` / `pl3` / `pl4` / `pr0` / `pr1` / `pr2` / `pr3` / `pr4` / `pt0` / `pt1` / `pt2` / `pt3` / `pt4` / `pv0` / `pv1` / `pv2` / `pv3` / `pv4`
+
+#### Positions <!-- notoc -->
+
+`absolute` / `bottom--1` / `bottom--2` / `bottom-0` / `bottom-1` / `bottom-2` / `fixed` / `left--1` / `left--2` / `left-0` / `left-1` / `left-2` / `relative` / `right--1` / `right--2` / `right-0` / `right-1` / `right-2` / `static` / `sticky` / `top--1` / `top--2` / `top-0` / `top-1` / `top-2`
+
+#### Selection <!-- notoc -->
+
+`noselect`
+
+#### Shadow <!-- notoc -->
+
+`box-shadow-1` / `box-shadow-2` / `box-shadow-3` / `box-shadow-4` / `box-shadow-i-1` / `box-shadow-i-2` / `box-shadow-i-3` / `box-shadow-i-4` / `text-shadow-1` / `text-shadow-2` / `text-shadow-3` / `text-shadow-4` / `text-shadow-5` / `text-shadow-6` / `text-shadow-7` / `text-shadow-8` / `text-shadow-9`
+
+#### Text align <!-- notoc -->
+
+`tc` / `tj` / `tl` / `tr`
+
 #### Text decorations <!-- notoc -->
 
 `no-underline` / `strike` / `underline`
@@ -617,25 +868,29 @@ Currently available CSS classes in MetaCSS base v0.0.1:
 
 `ttc` / `ttfsk` / `ttfw` / `tti` / `ttl` / `ttn` / `ttu`
 
-#### Text align <!-- notoc -->
+#### Undefined <!-- notoc -->
 
-`tc` / `tj` / `tl` / `tr`
+`vh-100` / `vh-25` / `vh-50` / `vh-75` / `vw-100` / `vw-25` / `vw-50` / `vw-75`
 
 #### Vertical align <!-- notoc -->
 
-`v-btm` / `v-mid` / `v-top`
+`v-base` / `v-btm` / `v-mid` / `v-top`
 
-#### Line heights <!-- notoc -->
+#### Visibility <!-- notoc -->
 
-`lh-copy` / `lh-double` / `lh-solid` / `lh-title`
+`hidden` / `visible`
 
 #### Whitespace <!-- notoc -->
 
 `ws-0` / `ws-1` / `ws-2`
 
-#### Letter spacing <!-- notoc -->
+#### Width <!-- notoc -->
 
-`ls--1` / `ls--2` / `ls-0` / `ls-1` / `ls-2` / `ls-3`
+`w-10` / `w-100` / `w-16` / `w-17` / `w-20` / `w-25` / `w-30` / `w-33` / `w-34` / `w-40` / `w-50` / `w-60` / `w-66` / `w-67` / `w-70` / `w-75` / `w-80` / `w-83` / `w-84` / `w-90` / `w1` / `w2` / `w3` / `w4` / `w5`
+
+#### Z-indices <!-- notoc -->
+
+`z-0` / `z-1` / `z-2` / `z-3` / `z-4` / `z-5` / `z-999` / `z-9999`
 
 ### Media queries
 
@@ -668,7 +923,7 @@ distributed as CLI bundle with **no runtime dependencies**. The following
 dependencies are only shown for informational purposes and are (partially)
 included in the bundle.
 
-Package sizes (brotli'd, pre-treeshake): ESM: 11.25 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 11.38 KB
 
 ## Dependencies
 
@@ -696,216 +951,6 @@ directory is using this package:
 |:-----------------------------------------------------------------------------------------------------------------------|:--------------------------------------|:------------------------------------------------------|:-----------------------------------------------------------------------------------|
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/meta-css-basics.png" width="240"/> | Basic thi.ng/meta-css usage & testbed | [Demo](https://demo.thi.ng/umbrella/meta-css-basics/) | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/meta-css-basics) |
 
-## CLI
-
-### Basic usage example
-
-The `metacss` tool provides multiple commands. You can install & run it like so:
-
-```text
-npx @thi.ng/meta-css --help
-
- █ █   █           │
-██ █               │
- █ █ █ █   █ █ █ █ │ @thi.ng/meta-css 0.0.1
- █ █ █ █ █ █ █ █ █ │ Data-driven CSS component & framework codegen
-                 █ │
-               █ █ │
-
-Usage: metacss <cmd> [opts] input [...]
-       metacss <cmd> --help
-
-Available commands:
-
-convert         : Transpile & bundle meta stylesheets to CSS
-export          : Export entire generated framework as CSS
-generate        : Generate framework rules from specs
-
-Flags:
-
--v, --verbose           Display extra process information
-
-Main:
-
--o STR, --out STR       Output file (or stdout)
-```
-
-### Generating framework code from bundled base definitions
-
-To create our first framework, we first need to generate CSS utility classes
-from given JSON generator specs. For simplicity the generated framework
-definitions will be stored as JSON too and then used as lookup tables for actual
-CSS translation in the next step.
-
-```bash
-# write generated CSS classes (in JSON)
-metacss generate --out framework.json node_modules/@thi.ng/meta-css/specs
-```
-
-### Generating CSS from `.meta` stylesheets
-
-#### *.meta stylesheets
-
-The naming convention used by the [default framework
-specs](https://github.com/thi-ng/umbrella/blob/develop/packages/meta-css/specs/)
-is loosely based on [tachyons.io](https://tachyons.io), with the important
-difference of media query handling. Using MetaCSS we don't have to pre-generate
-mediaquery-specific versions, and any class ID/token can be prefixed with an
-_arbitrary_ number of media query IDs (separated by `:`). These media queries
-are defined as part of the framework JSON specs and when used as a prefix,
-multiple query IDs can be combined freely. E.g. the token `dark:anim:bg-anim2`
-will auto-create a merged CSS `@media`-query block for the query IDs `dark` and
-`anim` and only emit the definition of `bg-anim2` for this combination (see
-generated CSS further below).
-
-readme.meta:
-
-```text tangle:export/readme.meta
-
-body { ma0 dark:bg-black dark:white bg-white black }
-
-#app { ma3 }
-
-.bt-group-v > a {
-    db w-100 l:w-50 ph3 pv2 bwb1
-    dark:bg-purple dark:white dark:b--black
-    light:bg-light-blue light:black light:b--white
-    {
-        :hover { bg-gold black anim:bg-anim2 }
-        :first-child { brt3 }
-        :last-child { brb3 bwb0 }
-    }
-}
-```
-
-readme2.meta:
-
-We will merge the definitions in this file with the ones from the file above
-(i.e. adding & overriding some of the declarations, here: border radius):
-
-```text tangle:export/readme2.meta
-#app { pa2 }
-
-.bt-group-v > a {
-    {
-        :first-child { brt4 }
-        :last-child { brb4 }
-    }
-}
-```
-
-```bash
-# if not out dir is specified writes result to stdout
-# use previously generated specs for resolving all identifiers & media queries
-metacss convert --pretty --specs framework.json readme.meta readme2.meta
-```
-
-#### Resulting CSS output
-
-```css
-/*! MetaCSS base v0.0.1 - generated by thi.ng/meta-css @ 2023-12-18T12:22:36.548Z */
-body {
-    margin: 0rem;
-    background-color: #fff;
-    color: #000;
-}
-
-#app {
-    margin: 1rem;
-    padding: .5rem;
-}
-
-.bt-group-v > a {
-    display: block;
-    width: 100%;
-    padding-left: 1rem;
-    padding-right: 1rem;
-    padding-top: .5rem;
-    padding-bottom: .5rem;
-    border-bottom-style: solid;
-    border-bottom-width: .125rem;
-}
-
-.bt-group-v > a:hover {
-    background-color: #ffb700;
-    color: #000;
-}
-
-.bt-group-v > a:first-child {
-    border-top-left-radius: 1rem;
-    border-top-right-radius: 1rem;
-}
-
-.bt-group-v > a:last-child {
-    border-bottom-left-radius: 1rem;
-    border-bottom-right-radius: 1rem;
-    border-bottom-style: solid;
-    border-bottom-width: 0rem;
-}
-
-@media (prefers-color-scheme:dark) {
-
-    body {
-        background-color: #000;
-        color: #fff;
-    }
-
-    .bt-group-v > a {
-        background-color: #5e2ca5;
-        color: #fff;
-        border-color: #000;
-    }
-
-}
-
-@media (min-width:60rem) {
-
-    .bt-group-v > a {
-        width: 50%;
-    }
-
-}
-
-@media (prefers-color-scheme:light) {
-
-    .bt-group-v > a {
-        background-color: #96ccff;
-        color: #000;
-        border-color: #fff;
-    }
-
-}
-
-@media not (prefers-reduced-motion) {
-
-    .bt-group-v > a:hover {
-        transition: 0.2s background-color ease-in-out;
-    }
-
-}
-```
-
-A simple HTML example using above MetaCSS styles:
-
-#### index.html
-
-```html tangle:export/index.html
-<!doctype html>
-<html>
-    <head>
-        <link rel="stylesheet" href="bundle.css"/>
-    </head>
-    <body>
-        <div id="app" class="bt-group-v">
-            <a href="#">One</a>
-            <a href="#">Two</a>
-            <a href="#">Three</a>
-            <a href="#">Four</a>
-        </div>
-    </body>
-</html>
-```
-
 ## Authors
 
 - [Karsten Schmidt](https://thi.ng)