Merge pull request #31 from minimaldesign/theme-architecture

Theme architecture: swappable skins with their own cascade layer

Author: minimaldesign

.github/workflows/ci.yml

@@ -40,8 +40,14 @@ jobs:
         run: |
           set -e
           # layers survived the build (the preset-env polyfill must stay off)
-          grep -q '@layer settings, base, elements, global, components, pages, helpers;' dist/mcss.css
+          grep -q '@layer settings, base, elements, global, components, theme, helpers;' dist/mcss.css
           ! grep -q ':not(#' dist/mcss.css
+          # the bundle ships zero-opinion: no theme content in mcss.css
+          # ('@layer theme' appears in a comment; check real block syntax)
+          ! grep -q '@layer theme {' dist/mcss.css
+          # per-file themes self-layer so any import method lands them right
+          grep -q '@layer theme {' dist/css/theme.wireframe.css
+          grep -q '@layer theme {' dist/css/theme.default.css
           # no unresolved custom media or mixins shipped
           # (plain '@custom-media' appears in a comment; check real syntax)
           ! grep -qE '@custom-media --|media \(--' dist/mcss.css

CLAUDE.md

@@ -25,7 +25,7 @@ mCSS is a CSS framework (ITCSS-based) paired with an Astro documentation site, c
 
 ## CSS cascade layers are load-bearing
 
-The framework uses native `@layer`; the layer name (declared in `src/styles/framework/mcss.css`) decides priority, and unlayered site CSS beats every layer. Import new framework files with `layer(<name>)`; never re-enable preset-env's `cascade-layers` polyfill in `postcss.config.cjs`. Always consult [agents/css.md](agents/css.md) before adding or moving CSS files.
+The framework uses native `@layer`; the layer name (declared in `src/styles/framework/mcss.css`) decides priority, and unlayered site CSS beats every layer. Import new framework files with `layer(<name>)`, except `theme.*.css` files: those wrap themselves in `@layer theme` and are activated from the consumer entry (`_global.css`), never imported by `mcss.css`. Never re-enable preset-env's `cascade-layers` polyfill in `postcss.config.cjs`. Always consult [agents/css.md](agents/css.md) before adding or moving CSS files.
 
 ## Detailed reference docs
 

DESIGN.md

@@ -137,7 +137,7 @@ components:
 
 mCSS is a utility-conscious CSS framework and documentation site with an ITCSS cascade, compact component classes, and design tokens stored as CSS custom properties. The visual identity is clean, technical, and documentation-first: blue interaction color, cool neutral surfaces, dense spacing, rounded-but-not-pill shapes, and system typography that keeps pages fast and readable.
 
-The canonical token sources are `src/styles/framework/settings.tokens.css` for raw scales and `src/styles/framework/settings.theme.default.css` for semantic theme and component defaults. This file translates those tokens into the DESIGN.md format for coding agents. When the CSS and this file disagree, the CSS source files win.
+The canonical token sources are `src/styles/framework/settings.tokens.css` for raw scales and `src/styles/framework/settings.ui.css` for semantic aliases and component defaults (interface tokens). This file translates those tokens into the DESIGN.md format for coding agents. When the CSS and this file disagree, the CSS source files win.
 
 ## Colors
 
@@ -202,13 +202,13 @@ Buttons use `.button` or `.bt`, with variants such as `.bt-primary`, `.bt-outlin
 
 Cards use `.card` with `.card-filled` and `.card-raised` variants. Keep internal spacing on `--card-spacing` and use `.card_header`, `.card_media`, `.card_content`, and `.card_actions` for composition.
 
-Tags, notices, avatars, headers, footers, hero controls, and the read-progress bar all have semantic custom properties in `settings.theme.default.css`. When creating a new component, add semantic tokens there before using raw scale values inside component CSS.
+Tags, notices, avatars, headers, footers, hero controls, and the read-progress bar all have semantic custom properties in `settings.ui.css`. When creating a new component, add interface tokens there before using raw scale values inside component CSS.
 
 Class naming is BEM-like with mCSS separators: `.block`, `.block_element`, `.block-modifier`, and `.is-*` state classes composed inside the block.
 
 ## Do's and Don'ts
 
-Do preserve the native cascade-layer setup: framework files import into named layers (`settings, base, elements, global, components, pages, helpers`) via `src/styles/framework/mcss.css`; site-only files import unlayered via `src/styles/_global.css`.
+Do preserve the native cascade-layer setup: framework files import into named layers (`settings, base, elements, global, components, theme, helpers`) via `src/styles/framework/mcss.css`; site-only files import unlayered via `src/styles/_global.css`.
 
 Do add new CSS files with the correct layer prefix, such as `component.name.css` or `help.name.css`, then import them with `layer(<name>)` in `framework/mcss.css` (framework) or plainly in `_global.css` (site).
 

agents/components.md

@@ -8,7 +8,7 @@
 4. **Rest spread**: `{...rest}` on the root element so consumers can set any native attribute.
 5. **`data-testid`**: accepted as a prop with a sensible per-component default.
 6. **States vs modifiers**: runtime states are `.is-*` classes (`.is-active`, `.is-online`); build-time variants are block modifiers (`.card-filled`). Prefer styling ARIA attributes when one exists (`[aria-current]`, `[aria-disabled]`).
-7. **Theme tokens**: every themable knob has a declared default in `settings.theme.default.css`; local-only custom properties use descriptive names (`--avatar-size`, not `--w`).
+7. **Interface tokens**: every themable knob has a declared default in `settings.ui.css`; local-only custom properties use descriptive names (`--avatar-size`, not `--w`).
 8. **Slots**: default slot for main content; named slots documented on the component's docs page.
 9. **A11y**: keyboard operable, labelled, JS motion gated on `prefers-reduced-motion`, no live-region roles on static content.
 

agents/css.md

@@ -9,25 +9,29 @@ mCSS uses **native CSS cascade layers** (`@layer`) on top of an ITCSS-inspired f
 ## Cascade rules (load-bearing)
 
 1. Framework layers, in priority order (later wins):
-   `settings, base, elements, global, components, pages, helpers`
+   `settings, base, elements, global, components, theme, helpers`
+   The order runs **from default to deliberate**: `settings` through `components` are the framework's defaults, `theme` is a deliberate override of those defaults, helpers are the last word. (Not "generic to specific": a theme is broad in reach but late in intent, and intent decides cascade order.)
 2. **Unlayered CSS beats every layer for normal declarations.** That's the consumer guarantee ("your CSS wins") and why site CSS is unlayered.
-3. **Helpers are the exception: every helper declaration carries `!important`.** Important layered declarations beat unlayered CSS (the cascade inverts for important), so helpers win over site and consumer CSS too. They're element-level overrides, like inline styling. For important declarations layer order also inverts (earlier layer wins), which is why the reduced-motion block in `base.reset.css` still beats helpers.
-4. `!important` is REQUIRED in every helper declaration and banned everywhere else in the framework, except the reduced-motion block in `base.reset.css` and third-party override files (see `site/external.astro.css`). `help.colors.css` and `help.spacing.css` get it from their generators.
-5. `postcss.config.cjs` disables preset-env's `cascade-layers` polyfill. **Never remove that option** — the polyfill strips every `@layer` rule and silently replaces the cascade with specificity hacks. The browser floor is set in `.browserslistrc` (`defaults and supports css-cascade-layers`).
+3. **The `theme` layer holds at most one active theme** (`theme.*.css`): token overrides plus optional skin rules. Theme files are self-layered (each wraps its own content in `@layer theme`) and are **never imported by `mcss.css`**; the consumer entry activates one (see `_global.css`). No theme = the default look. Unlayered consumer CSS still beats themes.
+4. **Helpers are the exception: every helper declaration carries `!important`.** Important layered declarations beat unlayered CSS (the cascade inverts for important), so helpers win over site and consumer CSS too. They're element-level overrides, like inline styling. For important declarations layer order also inverts (earlier layer wins), which is why the reduced-motion block in `base.reset.css` still beats helpers.
+5. `!important` is REQUIRED in every helper declaration and banned everywhere else in the framework, except the reduced-motion block in `base.reset.css` and third-party override files (see `site/external.astro.css`). `help.colors.css` and `help.spacing.css` get it from their generators.
+6. `postcss.config.cjs` disables preset-env's `cascade-layers` polyfill. **Never remove that option** — the polyfill strips every `@layer` rule and silently replaces the cascade with specificity hacks. The browser floor is set in `.browserslistrc` (`defaults and supports css-cascade-layers`).
 
 ## Layer table
 
 | Layer      | Prefix        | Purpose                                                     |
 | ---------- | ------------- | ----------------------------------------------------------- |
-| settings   | `settings.*`  | Tokens, themes (media queries + mixins import unlayered: build-time only) |
+| settings   | `settings.*`  | Primitive tokens (`settings.tokens.css`) and interface tokens (`settings.ui.css`); media queries + mixins import unlayered: build-time only |
 | base       | `base.*`      | Reset only (`base.reset.css`)                               |
 | elements   | `elements.*`  | Bare HTML element styles (text, form, media)                |
 | global     | `global.*`    | Structural patterns (a11y, grid, layout, prose, wrap)       |
 | components | `component.*` | Library components (card, hero, notice, …), including CSS-only single-class ones (badge, button, toggle) |
-| pages      | `page.*`      | Page-specific styles that helpers may override              |
+| theme      | `theme.*`     | Swappable skins: token overrides + skin rules, self-layered via `@layer theme`, activated by the consumer entry (never by `mcss.css`) |
 | helpers    | `help.*`      | Utility overrides (colors, spacing, typography), all `!important`: beats everything, including unlayered CSS |
 
-Site-only files keep the same prefixes but live in `src/styles/site/` and import unlayered (`component.header.css`, `page.docs.css`, `external.astro.css`, `devtools.css`, …).
+`page.*` is a file-naming convention only (page-specific styles, e.g. site `page.docs.css`); those files are plain unlayered consumer CSS, there is no `pages` layer.
+
+Site-only files keep the same prefixes but live in `src/styles/site/` and import unlayered (`component.header.css`, `page.docs.css`, `external.astro.css`, …). Debug helpers (`help.devtools.css`: baseline overlay, `.dev-error` toast) are framework helpers, not site CSS: framework components reference them.
 
 ## Class Naming (BEM-like, different separators)
 
@@ -51,13 +55,14 @@ A selector must only contain classes from its own block. Never write a descendan
 To style a component from outside:
 
 - **Its root**: mix your own class onto the element in markup (`<Section class="home_section …">`) and style that class.
-- **Its internals**: use the component's `<part>Class` props (`headerClass`, `titleClass`, …) to mix a class onto the part, or set the component's theme tokens on your own hook class. If neither exists yet, add the prop or token to the component. Do not reach in with a selector.
+- **Its internals**: use the component's `<part>Class` props (`headerClass`, `titleClass`, …) to mix a class onto the part, or set the component's interface tokens on your own hook class. If neither exists yet, add the prop or token to the component. Do not reach in with a selector.
 - **Bare HTML tags** (`.home_themer_formRow > button`), `.is-*` states, and ARIA attribute selectors are fine inside your own block.
 - **Context blocks are not components**: a component may reference the environment it sits in (`@scope (.prose) to (.not-prose)` in `component.notice.css`, `:root.theme-dark`), but the context's own file must never name specific components (that's why `global.prose.css` lists only bare tags).
+- **Theme files are the one sanctioned exception**: a `theme.*.css` file may select component classes from outside (`.card::after`, `.bt`) because a theme is by definition a skin over the whole system, versioned with the framework. Even there, prefer token overrides; reach for selectors only for what tokens can't express (pseudo-elements, `nth-child` rhythm, `text-decoration`).
 
 ### Token naming grammar
 
-Theme tokens are the public API of every component; they follow `--component-part-property`, longhand, kebab-case:
+Interface tokens (`settings.ui.css`) are the public API of every component; they follow `--component-part-property`, longhand, kebab-case:
 
 - `--bt-background-color-hover`, `--notice-border-width`, `--avatar-status-dot-color-online`
 - No abbreviations (`--card-bg-color` is legacy; new tokens spell out `background-color`), no camelCase, no underscores.
@@ -71,6 +76,7 @@ Never `transition: all` — it also transitions layout properties, so any late-a
 
 - **One block per file.** Every block gets its own file named after it (`.featureItem` lives in `component.featureItem.css`, never inside `component.featureGrid.css`), even for small companion blocks (`component.fieldRow.css`, site `component.webring.css`).
 - Framework file: create `src/styles/framework/<prefix>.<name>.css` and add `@import url(./<file>) layer(<layer>);` in the matching block of `framework/mcss.css`.
+- Theme file: create `src/styles/framework/theme.<name>.css` wrapping its own content in `@layer theme { … }`; do NOT import it in `mcss.css` (the consumer entry activates it; the dist index lists it commented out).
 - Site file: create `src/styles/site/<prefix>.<name>.css` and add a plain `@import` in `_global.css` (unlayered).
 - Framework CSS must never reference site-only selectors (e.g. `.expressive-code`); the site file mirrors any shared pattern itself.
 

agents/pitfalls.md

@@ -14,4 +14,4 @@ URLs for blog posts, docs, and component pages are derived from their file paths
 
 ## Theme Toggle
 
-The light/dark toggle persists in **`localStorage`** (key `theme`). The inline script in `BaseLayout.astro` applies the class before paint to avoid FOUC; the toggle behavior itself lives in `ThemeToggle.astro` (self-contained; rendered twice, its module script runs once). Don't introduce a second theme mechanism.
+The light/dark toggle persists in **`localStorage`** (key `theme`). The inline script in `BaseLayout.astro` applies the class before paint to avoid FOUC; the toggle behavior itself lives in `ThemeToggle.astro` (self-contained; rendered twice, its module script runs once). Don't introduce a second color-scheme mechanism. (Theme files, `theme.*.css`, are full skins and unrelated to the light/dark toggle.)

dist/css/component.prevNext.css

@@ -42,7 +42,7 @@ xxl: 1920px
   text-decoration: none;
   color: var(--text-color);
   border: var(--border-sm) solid var(--prevNext-border-color);
-  border-radius: var(--radius-lg);
+  border-radius: var(--prevNext-border-radius);
   transition: border-color var(--transition);
 }
 

dist/css/component.toggle.css

@@ -26,7 +26,7 @@ xxl: 1920px
 
 @layer components {
 .toggle {
-  /* Themable via the --toggle-* tokens in settings.theme.default.css */
+  /* Themable via the --toggle-* tokens in settings.ui.css */
   --toggle-w: var(--toggle-width);
   --toggle-h: var(--toggle-height);
   --toggle-bd: var(--toggle-border-width);

dist/css/elements.text.css

@@ -326,6 +326,7 @@ pre {
   font-family: var(--mono);
   font-size: 0.9rem;
   white-space: pre-wrap; /* override overflow default */
+  border-radius: var(--pre-border-radius);
 }
 
 q {

dist/css/help.devtools.css

@@ -0,0 +1,60 @@
+/*! mCSS v0.9.0 | MIT | https://mcss.dev */
+/*
+SETTINGS MEDIA QUERIES
+
+https://github.com/argyleink/open-props/blob/main/src/props.media.css
+https://open-props.style/#media-queries
+
+Can't use var() inside media queries 🤦‍♂️
+https://stackoverflow.com/questions/40722882/css-native-variables-not-working-in-media-queries/47212942#47212942
+so breakpoints are not in settings.tokens.css
+
+xxs: 240px
+xs: 360px
+sm: 480px
+md: 768px
+lg: 1024px
+xl: 1440px
+xxl: 1920px
+*/
+
+/* https://github.com/postcss/postcss-mixins */
+
+/* Example */
+
+/* truncate single line of text and adds … */
+
+@layer helpers {
+/* DEV TOOLS */
+
+/* Debug-only helpers, inert unless you add the classes yourself.
+   !important is intentional and required in the helpers layer: a debug
+   overlay must win over every other style, including unlayered CSS. */
+
+/* Baseline grid overlay: add .dev to <body> while checking vertical
+   rhythm (line spacing comes from --baseline in settings.tokens.css). */
+body.dev {
+  background-size: 100% calc(var(--baseline) * 1px) !important;
+  background-image: linear-gradient(
+    to bottom,
+    rgba(0, 0, 0, 0) calc((var(--baseline) - 1) * 1px),
+    hotpink calc(var(--baseline) * 1px)
+  ) !important;
+}
+
+/* Fixed error toast, used by components to surface dev-time mistakes
+   (see Hero.astro's slide count check). */
+.dev-error {
+  position: fixed !important;
+  top: var(--md1) !important;
+  left: var(--md1) !important;
+  z-index: var(--z-top) !important;
+  padding: var(--sm1) !important;
+  font-size: 1rem !important;
+  color: var(--danger-500) !important;
+  background: var(--danger-100) !important;
+  border: 1px solid var(--danger-500) !important;
+  border-radius: var(--radius-md) !important;
+}
+
+}