css-is-awesome 1.1.0

package/scss/recipes/dialog.md

@@ -0,0 +1,265 @@
+---
+name: dialog
+description: Accessible modal dialog built on the native HTML <dialog> element.
+category: overlay
+complexity: medium
+cia-version: ">=1.0.0"
+---
+
+## Use this when
+
+You need a modal — confirm, info, form, lightbox — that traps focus while open, returns focus on close, dismisses on Esc, and hides the background from screen readers. Use this recipe if you can target browsers with native `<dialog>` support (Baseline since 2022 across Chrome/Firefox/Safari/Edge). If you need older browser support, reach for a focus-trap library + `[role="dialog"]` div.
+
+## Structure (raw HTML)
+
+```html
+<dialog data-cia-recipe="dialog" aria-labelledby="my-dialog-title">
+  <header data-slot="header">
+    <h2 id="my-dialog-title">Dialog title</h2>
+    <button data-slot="close" aria-label="Close" formmethod="dialog">×</button>
+  </header>
+  <main data-slot="body">
+    Dialog body content goes here.
+  </main>
+  <footer data-slot="footer">
+    <button data-slot="cancel" formmethod="dialog">Cancel</button>
+    <button data-slot="confirm" autofocus>Confirm</button>
+  </footer>
+</dialog>
+```
+
+Notes on the markup:
+- `<dialog>` element is the source of truth — its `.showModal()` method does focus trap + Esc handling + `aria-modal` + backdrop, all natively
+- `aria-labelledby` points to the title element so screen readers announce the dialog by name on open
+- `formmethod="dialog"` on the cancel/close buttons closes the dialog without a JS handler when the dialog is inside a `<form>`
+- `autofocus` on the primary action sets initial focus when the dialog opens
+
+## Styling (cia mixins)
+
+```scss
+// MyDialog.module.scss — component stylesheet, so import the zero-emit barrel.
+@use 'css-is-awesome/api' as cia;
+
+.my-dialog {
+  @include cia.modal;
+
+  [data-slot="header"]  { @include cia.toolbar; }
+  [data-slot="body"]    { @include cia.stack($gap: 4); }
+  [data-slot="footer"]  { @include cia.toolbar; }
+
+  [data-slot="close"]   { @include cia.btn(ghost); margin-inline-start: auto; }
+  [data-slot="cancel"]  { @include cia.btn(ghost); }
+  [data-slot="confirm"] { @include cia.btn(primary); }
+}
+
+/* Backdrop is exposed by the browser via ::backdrop */
+.my-dialog::backdrop {
+  background: rgba(0, 0, 0, 0.5);
+  backdrop-filter: blur(2px);
+}
+```
+
+## Interactivity
+
+Native behavior of `<dialog>.showModal()`:
+- Renders above all other content in the top-layer
+- Adds `[open]` and `aria-modal="true"`
+- Traps Tab focus inside the dialog
+- Dismisses on Esc (calls `.close()` with no `returnValue`)
+- Disables interaction with the page behind it
+- Exposes `::backdrop` for backdrop styling
+
+To open: `dialogEl.showModal()`. To close: `dialogEl.close(optionalReturnValue)`. The return value is readable on the `close` event for "Cancel vs Confirm" wiring.
+
+Consumer responsibilities:
+- Show / close from your component logic (button clicks, route changes, etc.)
+- Optionally listen for the `close` event to read `returnValue`
+- If using `<form method="dialog">`, submit buttons close with `returnValue = button.value`
+
+No JS shim required for any of the above — every behavior is native.
+
+## A11y checklist
+
+- [ ] `aria-labelledby` points to the title element ([WAI-ARIA Authoring Practices: Dialog (Modal)](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/))
+- [ ] Initial focus on the primary action via `autofocus`, OR moved programmatically to the first focusable element on open
+- [ ] Background content has `inert` attribute when dialog is open (automatic with `.showModal()` — the top-layer hides everything from accessibility tree)
+- [ ] Esc closes the dialog (native to `<dialog>.showModal()`)
+- [ ] Close button has accessible name (`aria-label="Close"`)
+- [ ] Focus returns to the trigger element on close (browser handles this automatically when `.showModal()` was the open mechanism)
+- [ ] If dialog contains a `<form>`, use `method="dialog"` so submission closes the dialog naturally (avoids hand-wired close handlers)
+- [ ] Color contrast on `::backdrop` does not interfere with the dialog's own contrast budget ([WCAG 2.2 SC 1.4.11 Non-text Contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html))
+
+## Framework examples
+
+### React
+
+```tsx
+"use client";
+import { useRef } from "react";
+import styles from "./MyDialog.module.scss";
+
+export default function MyDialog() {
+  const ref = useRef<HTMLDialogElement>(null);
+
+  return (
+    <>
+      <button onClick={() => ref.current?.showModal()}>Open dialog</button>
+
+      <dialog
+        ref={ref}
+        className={styles.myDialog}
+        aria-labelledby="my-dialog-title"
+        onClose={(e) => {
+          // e.currentTarget.returnValue is the close value
+        }}
+      >
+        <header data-slot="header">
+          <h2 id="my-dialog-title">Delete record?</h2>
+          <button data-slot="close" formMethod="dialog" aria-label="Close">×</button>
+        </header>
+        <main data-slot="body">This action cannot be undone.</main>
+        <footer data-slot="footer">
+          <form method="dialog" style={{ display: "contents" }}>
+            <button data-slot="cancel" value="cancel">Cancel</button>
+            <button data-slot="confirm" value="confirm" autoFocus>Delete</button>
+          </form>
+        </footer>
+      </dialog>
+    </>
+  );
+}
+```
+
+### Vue
+
+```vue
+<script setup>
+import { ref } from "vue";
+const dialogRef = ref(null);
+const open = () => dialogRef.value?.showModal();
+</script>
+
+<template>
+  <button @click="open">Open dialog</button>
+
+  <dialog
+    ref="dialogRef"
+    class="my-dialog"
+    aria-labelledby="my-dialog-title"
+  >
+    <header data-slot="header">
+      <h2 id="my-dialog-title">Delete record?</h2>
+      <button data-slot="close" formmethod="dialog" aria-label="Close">×</button>
+    </header>
+    <main data-slot="body">This action cannot be undone.</main>
+    <footer data-slot="footer">
+      <form method="dialog" style="display: contents">
+        <button data-slot="cancel" value="cancel">Cancel</button>
+        <button data-slot="confirm" value="confirm" autofocus>Delete</button>
+      </form>
+    </footer>
+  </dialog>
+</template>
+```
+
+### Svelte
+
+```svelte
+<script>
+  let dialogEl;
+  const open = () => dialogEl?.showModal();
+</script>
+
+<button on:click={open}>Open dialog</button>
+
+<dialog
+  bind:this={dialogEl}
+  class="my-dialog"
+  aria-labelledby="my-dialog-title"
+>
+  <header data-slot="header">
+    <h2 id="my-dialog-title">Delete record?</h2>
+    <button data-slot="close" formmethod="dialog" aria-label="Close">×</button>
+  </header>
+  <main data-slot="body">This action cannot be undone.</main>
+  <footer data-slot="footer">
+    <form method="dialog" style="display: contents">
+      <button data-slot="cancel" value="cancel">Cancel</button>
+      <button data-slot="confirm" value="confirm" autofocus>Delete</button>
+    </form>
+  </footer>
+</dialog>
+```
+
+### Vanilla (Web Component)
+
+```js
+class MyDialog extends HTMLElement {
+  connectedCallback() {
+    this.innerHTML = `
+      <dialog aria-labelledby="my-dialog-title">
+        <header data-slot="header">
+          <h2 id="my-dialog-title">${this.getAttribute("title") ?? "Dialog"}</h2>
+          <button data-slot="close" formmethod="dialog" aria-label="Close">×</button>
+        </header>
+        <main data-slot="body"><slot></slot></main>
+        <footer data-slot="footer">
+          <form method="dialog" style="display: contents">
+            <button data-slot="cancel" value="cancel">Cancel</button>
+            <button data-slot="confirm" value="confirm" autofocus>OK</button>
+          </form>
+        </footer>
+      </dialog>
+    `;
+    this._dialog = this.querySelector("dialog");
+  }
+  open() { this._dialog?.showModal(); }
+  close(returnValue) { this._dialog?.close(returnValue); }
+}
+customElements.define("my-dialog", MyDialog);
+
+// usage in HTML:
+// <my-dialog title="Delete record?">This action cannot be undone.</my-dialog>
+// <script>document.querySelector('my-dialog').open();</script>
+```
+
+## Variants
+
+### Confirm / cancel only (no header dismiss)
+
+Drop the `[data-slot="close"]` button from the header. Esc still closes; the cancel button in the footer is the primary dismiss.
+
+### Drawer (slide-in from edge)
+
+Override `.my-dialog` with `inset-inline-end: 0; margin-inline: auto 0; block-size: 100dvh; max-block-size: none;` to anchor right edge, full height. Add a slide animation:
+
+```scss
+// Duration + easing come from the theme, so the drawer inherits each theme's
+// feel (Terminal snappy, Glass floaty) with no code change.
+.my-dialog[open] {
+  animation: slide-in var(--duration-normal, 240ms) var(--ease, ease) both;
+
+  @media (prefers-reduced-motion: reduce) {
+    animation-duration: 0.01ms;
+  }
+}
+@keyframes slide-in {
+  from { transform: translateX(100%); }
+  to   { transform: translateX(0); }
+}
+```
+
+cia's built-in keyframes are small entrance nudges, so a full-width drawer needs its own `@keyframes`. If an 8px slide is enough, skip the custom keyframe and use `@include cia.animate(slide-left);` — it reads the same duration/easing tokens and handles `prefers-reduced-motion` for you.
+
+## Pitfalls
+
+- **Form inside dialog with another method:** Setting `<form method="get">` etc. inside a `<dialog>` breaks the native close-on-submit. Either nest a separate `<form method="dialog">` around the close buttons OR handle submission explicitly with `event.preventDefault()` + `dialogEl.close()`.
+- **Stacking dialogs:** `.showModal()` puts the dialog in the top-layer. Nesting multiple modal dialogs works but each pushes the previous one further from focus; consider whether your UX really needs nested modals.
+- **iOS Safari quirks:** Older iOS Safari (< 17) had `::backdrop` rendering bugs and inconsistent scroll-lock. If you target older Safari, test the backdrop and consider a polyfill.
+- **`<dialog>` inside `display: contents` ancestors:** Some CSS layout edge cases can affect the top-layer rendering. If positioning looks off, check that ancestor `transform`, `filter`, or `perspective` isn't establishing a containing block.
+
+## Related recipes
+
+- [`bare-tags`](./_bare-tags.scss) — base bare `<dialog>` styling that applies if you skip a custom class name
+- (planned v1.1) `command-palette.md` — Cmd+K palette built on `<dialog>` + combobox pattern
+- (planned v1.1) `toast.md` — non-modal transient notifications (`[popover]` based)

package/scss/recipes/print-to-pdf.md

@@ -0,0 +1,263 @@
+---
+name: print-to-pdf
+description: Pixel-faithful PDF export from any page using only a @media print stylesheet — no library, no server.
+category: layout
+complexity: simple
+cia-version: ">=1.0.0"
+---
+
+## Use this when
+
+You want users to save a page as a faithful PDF — résumés, invoices, receipts, reports, tickets, order confirmations — and you'd rather not pay for a PDF service (DocRaptor, Prince, PDFShift) or pull in a rendering library. A browser already has a layout engine and a PDF writer wired together; you just describe the page *on paper* with `@media print`, and the user saves it from the print dialog. **The page itself is the PDF source — there's no second template to keep in sync.** If your "PDF" is really a fixed artifact unrelated to the page (a generated certificate, a pre-printed form to fill), this isn't it — use a real PDF library. If you need PDFs generated with no human present (emailing invoices, batch export), the *same stylesheet* still drives it — see the automation note under Interactivity.
+
+## Structure (raw HTML)
+
+There's almost nothing to add — the page **is** the structure. The only print-specific markup is marking the on-screen chrome that shouldn't appear on paper. Put `data-cia-recipe` on the document root so tooling can find it.
+
+```html
+<body data-cia-recipe="print-to-pdf">
+  <nav class="site-nav">…</nav>           <!-- hidden on paper -->
+
+  <main class="doc" data-slot="document">
+    <h1>Quarterly Report</h1>
+    <p>…</p>
+    <a href="https://example.com/details">Full details</a>
+  </main>
+
+  <footer class="site-footer">…</footer>  <!-- hidden on paper -->
+
+  <!-- Optional signpost. Ctrl+P works with or without it. -->
+  <button type="button" class="no-print" onclick="window.print()">Save as PDF</button>
+</body>
+```
+
+Notes on the markup:
+
+- **No button is required.** `@media print` applies to *every* print path — `Ctrl/Cmd+P`, File → Print, the dialog's built-in "Save as PDF" destination. The button is a discoverability signpost only; it says "this page was designed to become a PDF."
+- Mark every piece of site chrome — `nav`, `footer`, the button itself — so the print layer can hide it. A single shared class (`no-print`) plus your structural elements is enough.
+- The `<a>` keeps its real `href`. On paper a clickable link is dead, so we print the URL after it (see Pitfalls).
+
+## Styling (cia mixins)
+
+cia owns the `@media print` layer through four mixins. `print-base` ships the page-level defaults **on**; the rest are per-element.
+
+This recipe is the one case that spans **both** halves of cia's two-import model, so the code below is split accordingly. Both files import the same zero-emit authoring barrel, `css-is-awesome/api` — what differs is *where* the rules land.
+
+**1. In your GLOBAL stylesheet** — `print-base` emits its own `:root` block plus `@page`, so it must sit at the top level of a global/root stylesheet. Never put it inside a component module: a top-level `:root` is a hard build error under Next.js CSS Modules pure mode.
+
+```scss
+// app/globals.scss (or your single root stylesheet) — included ONCE.
+@use 'css-is-awesome/api' as cia;
+
+// Page-level defaults — at the ROOT, never inside a selector (it emits @page).
+// Sets the @page box and freezes animations so nothing prints invisible.
+// Defaults are on; toggle via args.
+@include cia.print-base;                            // size: letter, margin: 0.5in, freeze on
+// @include cia.print-base($size: A4, $margin: 0.75in);   // override the paper
+// @include cia.print-base($freeze-animations: false);    // opt out of the freeze
+
+// Make every light-dark() token resolve to its paper-friendly light value,
+// so a dark theme doesn't print as white-on-white. (See Pitfalls.)
+:root {
+  @include cia.print { color-scheme: light; }
+}
+
+// Hide site chrome on paper — the "hide the nav" case. Site chrome is global,
+// so these usually live here too; move them into the component that owns the
+// element if you'd rather keep the rule next to its markup.
+.site-nav,
+.site-footer,
+.no-print {
+  @include cia.print-hidden;
+}
+```
+
+**2. In each COMPONENT stylesheet** — everything else is per-element and emits nothing until you call a mixin, so it is safe in a `.module.scss`.
+
+```scss
+// Doc.module.scss — component stylesheet, so import the zero-emit barrel.
+@use 'css-is-awesome/api' as cia;
+
+// Co-locate per-element print overrides RIGHT NEXT TO the screen rule
+// they change, so the reason is visible where you read the original.
+.doc {
+  background: cia.color(surface-default);
+  color: cia.color(text-primary);
+
+  @include cia.print {
+    padding-block: 0;                 // strip screen chrome that wastes the sheet
+  }
+}
+```
+
+Show the minimum to make it work. The `color-scheme: light` flip is the cia-native fix for light-on-dark themes: instead of recoloring element by element, you tell the print sheet to use each token's light side once. Class names are consumer-chosen (`my-doc`, `.doc`) — never `cia-*`.
+
+### The variable filter system
+
+`print-base` emits three custom properties that are the control plane for the whole print layer — flip them and the output changes without rewriting a single rule:
+
+| Variable | Value | What it does |
+|---|---|---|
+| `--is-print` | `0` on screen, `1` on paper | A readable print-state switch. Use it in `calc()`, `opacity`, or `@container style(--is-print: 1)` to drive custom print-only effects. |
+| `--print-hide` | `none` | The `display` applied to `print-hidden` elements on paper. |
+| `--print-show` | `revert` | The `display` applied to `print-only` elements on paper. |
+
+Because the *value* is a variable, a per-element exception needs no new rule — just re-aim the variable on that element:
+
+```scss
+.legal-footer { @include cia.print-hidden; --print-hide: revert; } // keep this one ON paper
+.receipt-grid { @include cia.print-only;   --print-show: grid; }   // print-only block as a grid
+
+.cover { @include cia.print { opacity: var(--is-print); } }        // fades in only on paper
+```
+
+That is the whole reason this recipe needs no JavaScript and no headless-browser service: the media query plus a few variables **are** the engine.
+
+### Why these mixins use `!important`
+
+You will see `!important` in the compiled output. cia avoids it everywhere else; the print layer is a deliberate exception.
+
+`@media` contributes **no specificity**. `print-hidden` is included inside *your* selector, so its rule carries exactly your selector's specificity — and a later declaration at equal specificity wins, in print too:
+
+```scss
+.site-nav {
+  @include cia.print-hidden;   // @media print { display: none }
+  display: flex;               // equal specificity, later — would win without !important
+}
+```
+
+The competing rule is usually not even yours: a utility class, or a component library cia cannot see. Without `!important`, "hidden on paper" silently isn't — and it only shows up in a print preview.
+
+**`@layer` does not solve this.** Layered CSS always loses to unlayered CSS, so a layered print rule would lose to any consumer stylesheet that isn't layered — which is most of them. (`!important` also inverts layer order, so combining them misleads.) cia ships unlayered by design; see `.agent/decisions/decided/04-at-layer-decision.md`.
+
+The scope is small and the escape hatch is open: 8 declarations, all inside `@media print`, and every value stays variable-driven. Override `--print-hide` / `--print-show` to change *what* happens; you never have to fight the rule to win.
+
+## Interactivity
+
+**Zero JS.** The browser runs no script and needs no server — it reads your `@media print` rules and renders. The user presses `Ctrl/Cmd+P` (or File → Print) and picks the built-in "Save as PDF" destination. That is the entire mechanism.
+
+The only optional code is a **discoverability signpost** — a one-line button so users notice the page is built to be saved:
+
+```html
+<button type="button" class="no-print" onclick="window.print()">Save as PDF</button>
+```
+
+It's sugar over `window.print()` and nothing depends on it — `Ctrl+P` does the same job. Hide it on paper with `@include cia.print-hidden`. The framework examples below show this one button in each stack.
+
+## A11y checklist
+
+- [ ] Print output preserves DOM/reading order — the visual sheet follows source order ([WCAG 2.2 SC 1.3.2 Meaningful Sequence](https://www.w3.org/WAI/WCAG22/Understanding/meaningful-sequence.html))
+- [ ] Hiding chrome with `print-hidden` removes only navigation/controls, never content the document needs to make sense ([WCAG 2.2 SC 1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html))
+- [ ] Ink-on-paper contrast meets the minimum — the `color-scheme: light` flip keeps dark text on a light sheet ([WCAG 2.2 SC 1.4.3 Contrast (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html))
+- [ ] Link destinations survive on paper — print the `href` inline so a printed link is still followable ([WCAG 2.2 SC 2.4.4 Link Purpose (In Context)](https://www.w3.org/WAI/WCAG22/Understanding/link-purpose-in-context.html))
+- [ ] Animations are frozen and `opacity` forced to `1` in print so no content snapshots invisible (`print-base` does this by default)
+- [ ] The optional trigger is a real `<button type="button">` with a clear accessible name, hidden on paper ([WCAG 2.2 SC 4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html))
+
+## Framework examples
+
+All four are the same **optional** signpost button — the only framework-specific code in this recipe, and every one is a thin wrapper over `window.print()`. Hide it on paper with `@include cia.print-hidden` (or the `no-print` class).
+
+### React
+
+```tsx
+export function PrintButton({
+  children = "Save as PDF",
+  className,
+}: { children?: React.ReactNode; className?: string }) {
+  return (
+    <button type="button" className={className} onClick={() => window.print()}>
+      {children}
+    </button>
+  );
+}
+```
+
+### Vue
+
+```vue
+<template>
+  <button type="button" @click="() => window.print()">
+    <slot>Save as PDF</slot>
+  </button>
+</template>
+```
+
+### Svelte
+
+```svelte
+<button type="button" on:click={() => window.print()}>
+  <slot>Save as PDF</slot>
+</button>
+```
+
+### Vanilla (Web Component)
+
+```js
+class PrintButton extends HTMLElement {
+  connectedCallback() {
+    const btn = document.createElement("button");
+    btn.type = "button";
+    btn.textContent = this.textContent.trim() || "Save as PDF";
+    this.textContent = "";
+    btn.addEventListener("click", () => window.print());
+    this.appendChild(btn);
+  }
+}
+customElements.define("print-button", PrintButton);
+
+// Usage: <print-button>Save as PDF</print-button>
+```
+
+## Variants
+
+### International paper (A4) / landscape
+
+Pass the size through `print-base` (in the global stylesheet, at the root), and set orientation on `@page`:
+
+```scss
+// app/globals.scss — top level, not inside a selector, not in a component module
+@include cia.print-base($size: A4, $margin: 0.75in);
+
+@include cia.print {
+  @page { size: A4 landscape; }
+}
+```
+
+### Force a page break before a section
+
+Start a new sheet at a major boundary (a new invoice, a new chapter):
+
+```scss
+.section-start {
+  @include cia.print { break-before: page; }
+}
+```
+
+### Print-only content (URL footer, "printed on" stamp)
+
+Content that should appear *only* on paper, hidden on screen:
+
+```scss
+.print-footer { @include cia.print-only; }
+```
+
+## Pitfalls
+
+These are the bugs that *will* bite — each one cost real debugging time. This list is the value.
+
+- **Animations snapshot invisible.** Entrance fades and scroll reveals often start at `opacity: 0`; a PDF captured mid-animation prints **blank**. `print-base` collapses animations to zero duration and pins them to their final frame, so the fade lands visible. It does *not* force `opacity: 1` / `transform: none` — that would also flatten deliberate translucency and rotation. Elements that weren't animating keep their own styling. Keep the freeze on unless you have a specific reason not to.
+- **A blank trailing page.** A few invisible pixels of trailing `margin`/`padding`/`border` on the last element spill an empty final sheet. Zero them: `@include cia.print { .doc > :last-child { margin-block-end: 0; border-block-end: none; } }`. Also watch a full-height scroll/perspective wrapper (`height: 100vh`, `overflow`, `perspective`) — in print set `overflow: visible` and let content flow, or it clips paged output.
+- **Light-on-dark text becomes white-on-white.** Anything styled light text on a dark surface vanishes on a white sheet. The cia fix is the `color-scheme: light` flip in `print-base`'s block above — it lands every `light-dark()` token on its light value. For a one-off, override the single element with `@include cia.print { color: cia.color(text-secondary); }`.
+- **Background colors are off by default.** Browsers strip background colors and images when printing to save ink. If your design depends on them, tell users to tick "Background graphics" (Chrome) / "Print backgrounds" (Firefox/Safari) in the print dialog — there's no CSS that forces it on.
+- **Links lose their destination.** A clickable link is dead on paper — print the URL after it:
+  ```scss
+  @include cia.print {
+    a[href^="http"]::after { content: " (" attr(href) ")"; font-size: 0.85em; word-break: break-all; }
+  }
+  ```
+- **Page breaks split things awkwardly.** Keep headings with their content and don't split atomic blocks: `@include cia.print { h2, h3 { break-after: avoid; } li, .card { break-inside: avoid; } .doc { orphans: 3; widows: 3; } }`.
+- **`px` gets fuzzy in print.** Use `pt` / `in` for print typography and spacing — `px` is a screen unit and scales unpredictably across print zoom.
+
+## Related recipes
+
+- [`dialog`](./dialog.md) — a print-only summary often lives inside a confirmation dialog before export

package/scss/theme/README.md

@@ -0,0 +1,67 @@
+# scss/theme
+
+The canonical **token source** for css-is-awesome. These Sass partials are
+read at compile time by `_generator.scss` and the library mixins; they emit
+the baseline CSS custom properties on `:root` that the whole system reads
+through `var(--token, fallback)`. Edit a value here and rebuild — every
+component picks it up. This is library-author territory, not consumer
+territory.
+
+## scss/theme/ vs public/themes/
+
+Easy to confuse. They sit at opposite ends of the pipeline:
+
+| Layer | `scss/theme/` (this folder) | `public/themes/<name>/theme.css` |
+| --- | --- | --- |
+| When it runs | **Compile time** (Sass → CSS) | **Runtime** (browser, no build) |
+| Format | `_*.scss` partials, Sass maps | Plain CSS custom properties |
+| Audience | Library authors / contributors | Consumers swapping looks |
+| What it produces | The default `:root { … }` block | A `[data-theme="<name>"] { … }` override block |
+| Swap mechanism | Recompile the package | Drop in a new file, set `<html data-theme="…">` |
+| Source of truth for | Defaults, scales, contracts | One specific palette / mood |
+
+If you want to author a new theme, you almost certainly want
+[`../../CONTRIBUTING-THEMES.md`](../../CONTRIBUTING-THEMES.md), not this
+folder.
+
+## Files
+
+| File | Owns |
+| --- | --- |
+| `_index.scss` | Barrel. `@use`s every partial in cascade order and re-exports the maps with the `$theme-*` names the rest of the system expects. Also defines the spacing scale (`$space`, `$gap`, `$padding`, `$margin`) so spacing lives next to its sibling tokens. |
+| `_brand.scss` | `$brand` — primary / secondary / accent identity colors (and their hover/active variants). `_colors-light.scss` intentionally references these for `action-primary-*`. |
+| `_colors-light.scss` | `$colors-light` — semantic palette for light mode: backgrounds, surfaces, text, borders, interactive states, actions, status colors. |
+| `_colors-dark.scss` | `$colors-dark` — same semantic keys as light, dark-mode values. |
+| `_typography.scss` | `$fonts` — primary / secondary / mono font stacks. |
+| `_shape.scss` | `$radius` — border-radius scale (`none`, `sm`, `md`, `lg`, `xl`, `2xl`, `full`). |
+| `_shadows.scss` | `$shadows-light` / `$shadows-dark` — elevation scales. Numbered scale 1..5 is the source of truth; t-shirt aliases (`sm`..`2xl`) layer on top. |
+| `_icons.scss` | Icon configuration: SVG pack path (`$icon-path`, `$icon-pack`), default size, name aliases, and the Font Awesome wiring (`$fa-path`, `$fa-style`, `$fa-pro`). |
+| `_components.scss` | `$components` — per-component runtime override map (e.g. `btn-radius`, `btn-padding-y`). Each entry is emitted as a CSS custom property AND used as the fallback inside `var(--key, …)` in the matching mixin. Keep in sync with `scss/_mixins.scss` and `scss/components/*.scss`. |
+| `registry.json` | Static snapshot of preset palettes (sketchbook, royal-blue, grinning-gremlin, custom, etc.) carried over from the original boilerplate. **Not imported by the build, the validator, or the docs site** — it predates the runtime `public/themes/*` model. Treat it as historical reference; the live themes are the CSS files under `public/themes/`. |
+
+## Cascade order (`_index.scss`)
+
+```scss
+@use './brand'         as *;   // identity colors first — referenced by colors
+@use './colors-light'  as *;
+@use './colors-dark'   as *;
+@use './typography'    as *;
+@use './shape'         as *;
+@use './shadows'       as *;
+@use './components'    as *;   // last — may reference any of the above via var()
+```
+
+Order matters: `_colors-light.scss` reads `$brand` for `action-primary-*`,
+and `_components.scss` references the radius / spacing / color tokens that
+earlier partials define. Re-ordering will break compilation or silently
+swap defaults.
+
+## Adding a NEW theme
+
+You almost certainly do **not** edit this folder. Themes are runtime CSS
+files. See [`../../CONTRIBUTING-THEMES.md`](../../CONTRIBUTING-THEMES.md)
+for the contract, the validator, and the PR checklist.
+
+Edit this folder only when you are changing the **defaults the library
+itself ships with** — adding a new token to the contract, retuning the
+spacing scale, or wiring a new component map.

package/scss/theme/_brand.scss

@@ -0,0 +1,18 @@
+// ============================================================================
+// BRAND COLORS - Royal Blue Theme
+// ============================================================================
+// All colors WCAG AA compliant for accessibility
+// Note: action-primary-* in _colors-light.scss intentionally references these
+// brand values. Brand = identity, action-primary = semantic usage of brand.
+// ============================================================================
+
+$brand: (
+  primary:        #3A5FCD,
+  primary-hover:  #2E4A99,
+  primary-active: #1E3A8A,
+  secondary:      #FF6B6B,
+  secondary-hover:#E85555,
+  secondary-active:#C55,
+  accent:         #09F,
+  accent-hover:   #0088E6,
+) !default;