@rxova/brand 0.10.0 → 0.11.0

package/README.md

@@ -69,20 +69,27 @@ import { PROJECTS } from '@rxova/brand'
 ---
 ```
 
-`astro.css` pulls in `tokens.css` and adds the reset and base element styles
-that Starlight gives docs sites for free.
+`astro.css` pulls in `chrome.css` — the tokens, the footer's styles and the
+short aliases — and adds the reset and base element styles that Starlight gives
+docs sites for free.
+
+Use `chrome.css` on its own where something else already owns the document, such
+as rxova-website's shell templates: their body is composed into a built
+Starlight page, and the reset in `astro.css` is unlayered, so it would outrank
+everything in `@layer starlight.*` and flatten that page.
 
 ## What's in it
 
-| Export                            | What it is                                                            |
-| --------------------------------- | --------------------------------------------------------------------- |
-| `@rxova/brand`                    | `PROJECTS`, `docsUrl()`, `siteUrl()`, `sharedStarlightConfig()`       |
-| `@rxova/brand/tokens.css`         | The `--rx-*` custom properties. Everything derives from these.        |
-| `@rxova/brand/starlight.css`      | For docs sites: maps `--rx-*` onto Starlight's `--sl-*`, plus chrome  |
-| `@rxova/brand/astro.css`          | For plain Astro sites: tokens, a reset, and base element styling      |
-| `@rxova/brand/fonts.css`          | Self-hosted Space Grotesk + IBM Plex Mono                             |
-| `@rxova/brand/components/*.astro` | `SiteTitle`, `SocialIcons`, `Footer`, `SiteFooter`, `ProjectSwitcher` |
-| `@rxova/brand/assets/*`           | The mark, logos and per-project OG images                             |
+| Export                            | What it is                                                             |
+| --------------------------------- | ---------------------------------------------------------------------- |
+| `@rxova/brand`                    | `PROJECTS`, `docsUrl()`, `siteUrl()`, `sharedStarlightConfig()`        |
+| `@rxova/brand/tokens.css`         | The `--rx-*` custom properties. Everything derives from these.         |
+| `@rxova/brand/starlight.css`      | For docs sites: maps `--rx-*` onto Starlight's `--sl-*`, plus chrome   |
+| `@rxova/brand/astro.css`          | For plain Astro sites: `chrome.css`, a reset, and base element styling |
+| `@rxova/brand/chrome.css`         | What the shared header and footer need, with nothing document-level    |
+| `@rxova/brand/fonts.css`          | Self-hosted Space Grotesk + IBM Plex Mono                              |
+| `@rxova/brand/components/*.astro` | `SiteTitle`, `SocialIcons`, `Footer`, `SiteFooter`, `ProjectSwitcher`  |
+| `@rxova/brand/assets/*`           | The mark, logos and per-project OG images                              |
 
 ## The palette
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rxova/brand",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "type": "module",
   "description": "Design tokens, Starlight theme and shared site chrome for rxova.org",
   "keywords": [
@@ -33,6 +33,7 @@
     ".": "./src/index.ts",
     "./tokens.css": "./src/tokens.css",
     "./astro.css": "./src/astro.css",
+    "./chrome.css": "./src/chrome.css",
     "./starlight.css": "./src/starlight.css",
     "./fonts.css": "./src/fonts.css",
     "./components/*": "./src/components/*",

package/src/astro.css

@@ -1,42 +1,21 @@
 /**
- * Entry point for plain Astro surfaces — today, the rxova.org landing.
+ * Entry point for plain Astro surfaces that own their whole document — the
+ * rxova.org landing, /blog and /updates.
  *
  * Starlight sites use `starlight.css` instead; it maps the same tokens onto
- * Starlight's own variables. This file carries what a bare Astro page needs and
+ * Starlight's own variables. This file is `chrome.css` — the tokens, the footer
+ * and the short aliases — plus the two things a bare Astro page needs and
  * Starlight already provides: a reset and base element styling.
  *
- * It also aliases the short token names the landing was written against
- * (`--bg`, `--fg`, `--rule`, …) onto their `--rx-*` equivalents, so adopting
- * this package did not require rewriting several hundred lines of scoped
- * component styles in one go. New work should use `--rx-*` directly; the
- * aliases exist to make the migration incremental, not to be a second API.
+ * Load this only where nothing else owns the document. A surface that renders
+ * the shared chrome *into* someone else's document — rxova-website's shell
+ * templates, whose body is composed into a built Starlight page — must load
+ * `chrome.css` instead. The reset below is unlayered, so inside a Starlight
+ * document it would outrank every rule in `@layer starlight.*` and flatten the
+ * page; see chrome.css.
  */
 
-@import './tokens.css';
-/* The shared site footer, which /blog, /updates and the landing all render. It
-   is the one piece of chrome common to these surfaces and the Starlight ones,
-   so its rules sit in their own file and both entry points pull them in. */
-@import './footer.css';
-
-:root {
-  --bg: var(--rx-bg);
-  --fg: var(--rx-fg);
-  --muted: var(--rx-muted);
-  --faint: var(--rx-faint);
-  --rule: var(--rx-rule);
-  --card: var(--rx-card);
-  --tag-bg: var(--rx-tag-bg);
-  --glow-tint: var(--rx-glow-tint);
-  --font: var(--rx-font-sans);
-  --mono: var(--rx-font-mono);
-  --max: var(--rx-max);
-
-  /* The landing's `--accent` is the foreground, not the brand violet: its
-     design is deliberately monochrome and uses the gradient only as an accent
-     rule. Mapping this to --rx-primary would tint every focus ring on the
-     site. */
-  --accent: var(--rx-fg);
-}
+@import './chrome.css';
 
 /* --- Reset ---------------------------------------------------------------- */
 

package/src/chrome.css

@@ -0,0 +1,51 @@
+/**
+ * Everything the shared chrome needs, and nothing that touches the document.
+ *
+ * `Header`, `SiteFooter` and `ThemeToggle` are rendered on two kinds of page:
+ * plain Astro surfaces that own their whole document (the landing, /blog,
+ * /updates — see astro.css), and rxova-website's shell templates, whose body is
+ * composed into an already-complete Starlight document at deploy time.
+ *
+ * The second case is why this file exists. It carries the tokens, the footer's
+ * styles and the short aliases the chrome's scoped CSS is written against — but
+ * no reset and no base element styling. Those belong to whoever owns the
+ * document, and a shell that brings its own into a Starlight page destroys that
+ * page: Starlight puts all of its CSS in `@layer starlight.*`, and an unlayered
+ * `* { margin: 0; padding: 0 }` arriving from the shell beats every layered rule
+ * it has, whatever the specificity. That is not a hypothetical — it flattened
+ * every /packages/* docs page on rxova.org.
+ *
+ * So: load this to render the chrome, and astro.css (which is this plus the
+ * reset) to own a document.
+ */
+
+@import './tokens.css';
+/* The shared site footer, which /blog, /updates and the landing all render. It
+   is the one piece of chrome common to these surfaces and the Starlight ones,
+   so its rules sit in their own file and both entry points pull them in. */
+@import './footer.css';
+
+/* The short token names the landing and the shared chrome were written against
+   (`--bg`, `--fg`, `--rule`, …), aliased onto their `--rx-*` equivalents, so
+   adopting this package did not require rewriting several hundred lines of
+   scoped component styles in one go. New work should use `--rx-*` directly; the
+   aliases exist to make the migration incremental, not to be a second API. */
+:root {
+  --bg: var(--rx-bg);
+  --fg: var(--rx-fg);
+  --muted: var(--rx-muted);
+  --faint: var(--rx-faint);
+  --rule: var(--rx-rule);
+  --card: var(--rx-card);
+  --tag-bg: var(--rx-tag-bg);
+  --glow-tint: var(--rx-glow-tint);
+  --font: var(--rx-font-sans);
+  --mono: var(--rx-font-mono);
+  --max: var(--rx-max);
+
+  /* The landing's `--accent` is the foreground, not the brand violet: its
+     design is deliberately monochrome and uses the gradient only as an accent
+     rule. Mapping this to --rx-primary would tint every focus ring on the
+     site. */
+  --accent: var(--rx-fg);
+}

package/src/footer.css

@@ -7,9 +7,9 @@
  * is why /blog and /updates shipped a dot-separated link row instead — the
  * shared footer would have rendered unstyled there.
  *
- * Imported by both `starlight.css` and `astro.css`; nothing needs to import it
+ * Imported by both `starlight.css` and `chrome.css`; nothing needs to import it
  * directly. Written against `--rx-*` tokens only, so it does not depend on the
- * short aliases astro.css defines.
+ * short aliases chrome.css defines.
  */
 
 @import './tokens.css';