/*
 * themes/default/assets/theme.css — the theme stylesheet.
 *
 * This file is a STARTER. It is deliberately all comments, so a fresh clone
 * renders exactly as it did before theme stylesheets existed. Uncomment
 * something, or replace the whole file, and it applies.
 *
 * ---------------------------------------------------------------------------
 * THE SPLIT: theme.json owns VALUES, theme.css owns RULES.
 * ---------------------------------------------------------------------------
 *
 * theme.json (one level up, beside this `assets/` directory) sets ten tokens —
 * colors, font stack, base size, heading weight, radius, max width. Those
 * become `--site-*` custom properties in an inline <style> block on every
 * public page. That block carries the CSP nonce, which is why every value in
 * theme.json is strictly shape-checked and cannot contain `;`, `{`, `}` or a
 * newline.
 *
 * This file has no such limits, because it is not spliced into anything: it is
 * served whole from our own origin as text/css, which `style-src 'self'`
 * already permits. So anything CSS can express belongs here — selectors,
 * @media, @font-face, pseudo-elements, whole component looks.
 *
 * Rule of thumb: if a designer would want to change it per install, make it a
 * token. If it is *how* the site is put together, write it here.
 *
 * ---------------------------------------------------------------------------
 * WHERE IT SITS IN THE CASCADE
 * ---------------------------------------------------------------------------
 *
 *     public/css/site.css     the platform's own baseline
 *     /theme/theme.css        this file  <-- you are here
 *     module CSS              a module's own sheet, if it ships one
 *     inline --site-* tokens  theme.json, in a nonce'd <style> block
 *
 * So this file can restyle anything site.css set, and the tokens resolve last,
 * which is what lets a rule written here consume a value chosen there.
 *
 * ---------------------------------------------------------------------------
 * WHAT IS SERVED, AND WHAT IS NOT
 * ---------------------------------------------------------------------------
 *
 * Everything in `themes/<name>/assets/` is served under `/theme/`, and ONLY for
 * the theme that `THEME` selected. `theme.json` is one level up, outside
 * `assets/`, and is never reachable. A font placed beside this file is fetched
 * at `/theme/<filename>`.
 *
 * ---------------------------------------------------------------------------
 * CONSUMING THE TOKENS
 * ---------------------------------------------------------------------------
 *
 * Always give `var()` a fallback. A token can be refused at load time (a bad
 * value in theme.json defaults instead of applying), and a rule with no
 * fallback would then resolve to nothing at all rather than to the default.
 *
 *     .hero {
 *       background: var(--site-primary, #1F2937);
 *       color: var(--site-paper, #FFFFFF);
 *       border-radius: var(--site-radius, 14px);
 *       padding: 4rem 2rem;
 *     }
 *
 *     .hero p {
 *       color: var(--site-muted, #516072);
 *       max-width: 42ch;
 *     }
 *
 *     h1, h2, h3 {
 *       font-weight: var(--site-heading-weight, 800);
 *       letter-spacing: -0.02em;
 *     }
 *
 * The ten available properties: --site-primary, --site-accent, --site-paper,
 * --site-ink, --site-muted, --site-font, --site-font-size,
 * --site-heading-weight, --site-radius, --site-max-width.
 *
 * ---------------------------------------------------------------------------
 * A WEBFONT
 * ---------------------------------------------------------------------------
 *
 * `fontStack` in theme.json cannot contain `url()` — parentheses are refused
 * there on purpose — so an @font-face rule lives here instead. Drop the font
 * file into this same `assets/` directory and reference it by a path relative
 * to this stylesheet:
 *
 *     @font-face {
 *       font-family: 'Equinox';
 *       src: url('equinox.woff2') format('woff2'),
 *            url('equinox.woff')  format('woff');
 *       font-weight: 400;
 *       font-style: normal;
 *       font-display: swap;
 *     }
 *
 * Then name it first in theme.json's `fontStack`, with a real fallback after
 * it, so the site still reads if the file 404s:
 *
 *     "fontStack": "Equinox, Georgia, serif"
 *
 * `font-display: swap` matters: without it a slow font blanks the text.
 *
 * A font uploaded through Admin -> Media instead is served from the object
 * storage bucket, which CSP `font-src` also allows — use its full URL in the
 * `src` in that case.
 *
 * ---------------------------------------------------------------------------
 * NOTES
 * ---------------------------------------------------------------------------
 *
 * - This file is read by the browser, not by the app, so a syntax error here
 *   cannot break a boot or throw a 500. It fails the way bad CSS always fails:
 *   the offending rule is skipped and everything else applies.
 * - Do not target the admin panel. Nothing under /admin loads this file or any
 *   --site-* token, and that insulation is asserted by the test suite — a theme
 *   must not be able to make the panel unusable, since fixing a theme needs it.
 * - EDITING this file needs no restart: the app never reads its contents, it
 *   only serves them. CREATING it where there was none does need one, because
 *   whether the <link> is emitted at all is decided once at boot.
 */