@cparkerwebm/webmonterey 1.0.0

package/src/pages/robots.txt.ts

@@ -0,0 +1,41 @@
+/*
+ * robots.txt, GENERATED — not a file in public/.
+ *
+ * It used to live in public/, which is copied verbatim and therefore cannot read
+ * webmonterey.json. That left the `Sitemap:` line commented out with an instruction to write
+ * the domain in by hand at launch: one manual step, on one line, in a file nobody looks at
+ * again, whose omission is completely silent. Every site that forgot it simply had no sitemap
+ * submitted.
+ *
+ * As an endpoint it is correct by construction. `output: 'static'` prerenders this at build,
+ * so the deployed result is still a plain static file with no runtime cost — check
+ * dist/client/robots.txt after a build.
+ *
+ * The Sitemap line is emitted ONLY when `domain` is set, because that is exactly the
+ * condition under which @astrojs/sitemap generates the file at all (it needs an absolute URL).
+ * Advertising a sitemap that was never built is worse than advertising none.
+ *
+ * WORTH KNOWING WHEN THIS FILE LOOKS WRONG IN PRODUCTION: if AI/search signals are configured
+ * on the Cloudflare zone, Cloudflare PREPENDS its own managed block to the response and keeps
+ * this content below it. Both are served; neither replaces the other. Read past the header
+ * before concluding the file has been overwritten.
+ */
+import type { APIRoute } from 'astro';
+
+export const GET: APIRoute = ({ site }) => {
+  const lines = ['User-agent: *', 'Allow: /'];
+
+  /*
+   * Deliberately no Disallow for noindex routes. Blocking a path here stops crawlers fetching
+   * it, which means they never see its noindex tag — and an inbound link can then get the URL
+   * indexed anyway, with no description. To exclude a page you must let it be crawled. The
+   * sitemap `filter` in astro.config.mjs is what keeps those routes out.
+   */
+  if (site) {
+    lines.push('', `Sitemap: ${new URL('sitemap-index.xml', site).href}`);
+  }
+
+  return new Response(`${lines.join('\n')}\n`, {
+    headers: { 'Content-Type': 'text/plain; charset=utf-8' },
+  });
+};

package/src/pages/webm.astro

@@ -0,0 +1,23 @@
+---
+/*
+ * WORKSPACE — a scratch page for building components.
+ *
+ * Drop a component in here to look at it in isolation before wiring it into a real page.
+ * Nothing here ships to visitors: the page is `noindex, nofollow` and excluded from the
+ * sitemap (see NOINDEX_ROUTES in astro.config.mjs).
+ *
+ * It is NOT linked from anywhere. Reach it directly at /webm.
+ *
+ * Leave it empty when you are done — anything left behind renders on every deploy, including
+ * production.
+ */
+import Base from '../layouts/base.astro';
+---
+
+<Base title="WebMonterey Workspace" noindex>
+  <section class="webm-section">
+    <div class="webm-container">
+      <!-- Build here. -->
+    </div>
+  </section>
+</Base>

package/src/styles/base.css

@@ -0,0 +1,185 @@
+/*
+ * webm.base — element defaults and page-level primitives.
+ * Everything here is driven by tokens. No literal colors, sizes, or durations.
+ */
+
+@layer webm.base {
+  :root {
+    color-scheme: light;
+
+    /*
+     * Focus Not Obscured (WCAG 2.4.11) and anchor targets.
+     *
+     * Once a site has a sticky header region, anything the browser scrolls into view — an
+     * element receiving focus via Tab, a #hash target, the skip link — would otherwise land
+     * underneath it and be invisible while focused.
+     *
+     * A header component sets --webm-header-height itself. The fallback below keeps the
+     * behavior sane before one exists.
+     */
+    --webm-header-height: 0px;
+
+    scroll-padding-block-start: calc(var(--webm-header-height) + var(--webm-space-sm));
+  }
+
+  body {
+    background-color: var(--webm-surface);
+    color: var(--webm-text);
+    font-family: var(--webm-font-sans);
+    font-size: var(--webm-font-size-sm);
+    line-height: var(--webm-leading-normal);
+  }
+
+  /* --- type scale ---------------------------------------------------------- */
+
+  h1,
+  .webm-h1 {
+    font-size: var(--webm-font-size-3xl);
+    line-height: var(--webm-leading-tight);
+    letter-spacing: var(--webm-tracking-tight);
+    font-weight: var(--webm-weight-bold);
+  }
+
+  h2,
+  .webm-h2 {
+    font-size: var(--webm-font-size-2xl);
+    line-height: var(--webm-leading-tight);
+    letter-spacing: var(--webm-tracking-tight);
+    font-weight: var(--webm-weight-bold);
+  }
+
+  h3,
+  .webm-h3 {
+    font-size: var(--webm-font-size-xl);
+    line-height: var(--webm-leading-snug);
+    font-weight: var(--webm-weight-semibold);
+  }
+
+  h4,
+  .webm-h4 {
+    font-size: var(--webm-font-size-lg);
+    line-height: var(--webm-leading-snug);
+    font-weight: var(--webm-weight-semibold);
+  }
+
+  h5,
+  .webm-h5 {
+    font-size: var(--webm-font-size-md);
+    line-height: var(--webm-leading-snug);
+    font-weight: var(--webm-weight-semibold);
+  }
+
+  h6,
+  .webm-h6 {
+    font-size: var(--webm-font-size-sm);
+    line-height: var(--webm-leading-normal);
+    font-weight: var(--webm-weight-semibold);
+    letter-spacing: var(--webm-tracking-wide);
+    text-transform: uppercase;
+  }
+
+  small,
+  .webm-small {
+    font-size: var(--webm-font-size-xs);
+  }
+
+  code,
+  kbd,
+  samp,
+  pre {
+    font-family: var(--webm-font-mono);
+    font-size: 0.9em;
+  }
+
+  /* --- links --------------------------------------------------------------- */
+
+  a {
+    color: var(--webm-link);
+  }
+
+  a:hover {
+    color: var(--webm-link-hover);
+  }
+
+  /* --- focus --------------------------------------------------------------- */
+
+  :focus-visible {
+    /*
+     * COMPOSED FROM THE PARTS, not from --webm-focus-ring.
+     *
+     * A custom property containing var() is resolved where it is DECLARED. --webm-focus-ring is
+     * declared on :root, so it resolves to "3px solid <action>" there and inherits down already
+     * resolved - a component setting --webm-focus-color further down the tree changed nothing at
+     * all. Any component on a colored surface was therefore stuck with the site-wide action
+     * color, which is an accessibility failure with no symptom in code review.
+     *
+     * friendsofthemarinalibrary.org fixed this inside its own copy of base.css; every other site
+     * still had it.
+     *
+     * --webm-focus-ring stays defined in the token set: it is a reasonable thing for a client to
+     * reference, and removing it would break any site that does. It is simply not consumed here.
+     */
+    outline: var(--webm-focus-width) solid var(--webm-focus-color);
+    outline-offset: var(--webm-focus-offset);
+  }
+
+  /* --- landmarks ----------------------------------------------------------- */
+
+  /* Required for the skip link to actually move focus in Safari. */
+  #webm-main:focus {
+    outline: none;
+  }
+
+  /* --- skip link ----------------------------------------------------------- */
+
+  .webm-skip-link {
+    position: absolute;
+    inset-inline-start: var(--webm-space-sm);
+    inset-block-start: var(--webm-space-sm);
+    z-index: var(--webm-z-skiplink);
+    padding: var(--webm-space-xs) var(--webm-space-md);
+    background-color: var(--webm-surface);
+    color: var(--webm-text);
+    border-radius: var(--webm-radius-sm);
+    box-shadow: var(--webm-shadow-md);
+    translate: 0 -200%;
+  }
+
+  .webm-skip-link:focus-visible {
+    translate: 0 0;
+  }
+
+  /* --- horizontal rule ----------------------------------------------------- */
+
+  hr {
+    border: 0;
+    border-block-start: var(--webm-border-width-1) solid var(--webm-border-subtle);
+    margin-block: var(--webm-space-lg);
+  }
+
+  /* --- selection ----------------------------------------------------------- */
+
+  ::selection {
+    background-color: var(--webm-surface-accent);
+    color: var(--webm-text-strong);
+  }
+
+  /* --- motion -------------------------------------------------------------- */
+
+  @media (prefers-reduced-motion: no-preference) {
+    html {
+      scroll-behavior: smooth;
+    }
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    *,
+    *::before,
+    *::after {
+      animation-duration: 0.01ms !important;
+      animation-iteration-count: 1 !important;
+      transition-duration: 0.01ms !important;
+      scroll-behavior: auto !important;
+    }
+  }
+}

package/src/styles/global.css

@@ -0,0 +1,47 @@
+/*
+ * The package's stylesheet. Everything package-owned, in cascade order.
+ *
+ * LAYER ORDER. Later layers win.
+ *
+ *   webm.reset       browser normalization
+ *   webm.tokens      custom properties - COMPILED FROM design.json, see below
+ *   webm.base        element defaults, a11y primitives
+ *   webm.layout      section/container/grid primitives
+ *   webm.components  .core then .custom  <- the client override seam
+ *   webm.utilities   single-purpose helpers
+ *   webm.overrides   per-client escape hatch, highest priority
+ *
+ * THE BARE @layer STATEMENT BELOW DOES NOT SURVIVE THE BUILD. Verified in generation 2: it is
+ * absent from dist/client/_astro/*.css. Wrapping each file in `@layer name { ... }` preserves
+ * each layer's MEMBERSHIP but says nothing about the ORDER of the layers - and order is the
+ * entire point. With the statement gone, order falls back to first appearance in whatever the
+ * bundler emitted. A component's scoped style landing ahead of this file was enough to put
+ * webm.components.core before webm.reset, at which point `img { max-inline-size: 100% }` beat a
+ * component's `max-inline-size: 11.25rem` and rendered a 180px logo at 883px.
+ *
+ * Correctness therefore comes from base.astro, which emits this same statement as an inline
+ * <style is:inline> ahead of every stylesheet, where nothing can bundle it away.
+ *
+ * >> THE TWO LISTS MUST MATCH. Change this one and you must change base.astro's. <<
+ * webm doctor checks that they do.
+ *
+ * WHAT CHANGED FROM GENERATION 2: tokens.css is gone. The token layer is compiled from the
+ * client's design.json into a virtual module, which base.astro imports. There is no tokens.css
+ * to @import here and nothing to edit by hand - `webm design:extract` migrates an existing one.
+ *
+ * custom/_index.css is also absent, because it lives in the CLIENT repo and a package cannot
+ * reach it. The client's own src/styles/index.css imports this file and then theirs, which is
+ * what keeps webm.components.custom beating webm.components.core without !important.
+ *
+ * An EMPTY @layer block is dropped by the minifier, which is why webm.components.custom and
+ * webm.overrides are absent from built CSS until a client writes a rule.
+ */
+
+@layer webm.reset, webm.tokens, webm.base, webm.layout, webm.components.core,
+  webm.components.custom, webm.utilities, webm.overrides;
+
+@import url('./reset.css');
+@import url('./base.css');
+@import url('./layout.css');
+@import url('./utilities.css');
+@import url('../includes/webmonterey/animations/animations.css');

package/src/styles/layers.test.ts

@@ -0,0 +1,32 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { LAYERS, LAYER_STATEMENT } from './layers.ts';
+
+/** The @layer statement in global.css, normalized to a single line. */
+function statementFrom(path: string): string {
+  const css = readFileSync(new URL(path, import.meta.url), 'utf8').replace(/\/\*[\s\S]*?\*\//g, '');
+  const m = css.match(/@layer\s+([^;]+);/);
+  assert.ok(m, `no @layer statement found in ${path}`);
+  return m[1]!
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .join(', ');
+}
+
+test('global.css declares exactly the layers in layers.ts, in order', () => {
+  assert.equal(statementFrom('./global.css'), LAYERS.join(', '));
+});
+
+test('the statement puts tokens above reset and below components', () => {
+  const i = (n: string) => LAYERS.indexOf(n as (typeof LAYERS)[number]);
+  assert.ok(i('webm.reset') < i('webm.tokens'), 'reset must not beat tokens');
+  assert.ok(i('webm.tokens') < i('webm.components.core'), 'tokens must lose to components');
+  assert.ok(i('webm.components.core') < i('webm.components.custom'), 'the client seam must win');
+  assert.ok(i('webm.overrides') === LAYERS.length - 1, 'overrides is the last word');
+});
+
+test('LAYER_STATEMENT is a single valid statement', () => {
+  assert.match(LAYER_STATEMENT, /^@layer [\w., ]+;$/);
+});

package/src/styles/layers.ts

@@ -0,0 +1,21 @@
+/*
+ * The layer order, as data.
+ *
+ * Declared in exactly one place so global.css, base.astro's inline statement and `webm doctor`
+ * cannot drift apart. In generation 2 the two lists were kept in step by a comment saying they
+ * must be - which is a convention, not a mechanism, and the failure is invisible: a mismatched
+ * order produces no error, just a cascade that inverts on some pages and not others.
+ */
+export const LAYERS = [
+  'webm.reset',
+  'webm.tokens',
+  'webm.base',
+  'webm.layout',
+  'webm.components.core',
+  'webm.components.custom',
+  'webm.utilities',
+  'webm.overrides',
+] as const;
+
+/** The `@layer a, b, c;` statement. base.astro emits this inline, ahead of every stylesheet. */
+export const LAYER_STATEMENT = `@layer ${LAYERS.join(', ')};`;

package/src/styles/layout.css

@@ -0,0 +1,235 @@
+/*
+ * webm.layout — the structural primitives every page block is built from.
+ *
+ * MODEL: every block is a full-bleed row (.webm-section) wrapping a constrained inner
+ * (.webm-container). --webm-width-max is the SITE bound; prose additionally constrains to
+ * --webm-width-text or line length becomes unreadable.
+ *
+ * Variants are data attributes, not modifier classes, so a component can pass them straight
+ * through from its schema: <section class="webm-section" data-tone={tone}>
+ */
+
+@layer webm.layout {
+  /* --- full-bleed row ------------------------------------------------------ */
+
+  .webm-section {
+    inline-size: 100%;
+    padding-block: var(--webm-section-md);
+    background-color: var(--webm-surface);
+  }
+
+  .webm-section:where([data-tone='alt']) {
+    background-color: var(--webm-surface-alt);
+  }
+
+  .webm-section:where([data-tone='inverse']) {
+    background-color: var(--webm-surface-inverse);
+    color: var(--webm-text-inverse);
+  }
+
+  .webm-section:where([data-tone='accent']) {
+    background-color: var(--webm-surface-accent);
+    color: var(--webm-text-strong);
+  }
+
+  .webm-section:where([data-space='none']) {
+    padding-block: 0;
+  }
+  .webm-section:where([data-space='sm']) {
+    padding-block: var(--webm-section-sm);
+  }
+  .webm-section:where([data-space='lg']) {
+    padding-block: var(--webm-section-lg);
+  }
+  .webm-section:where([data-space='xl']) {
+    padding-block: var(--webm-section-xl);
+  }
+
+  /* --- constrained inner --------------------------------------------------- */
+
+  /*
+   * `inline-size: min(100% - 2*gutter, MAX)` rather than `max-width + padding-inline`:
+   * the CONTENT box is then exactly MAX at large viewports regardless of box-sizing,
+   * and no calc() on max-width is needed.
+   */
+  .webm-container {
+    inline-size: min(
+      100% - (var(--webm-gutter) * 2),
+      var(--webm-container-width, var(--webm-width-max))
+    );
+    margin-inline: auto;
+  }
+
+  .webm-container:where([data-width='wide']) {
+    --webm-container-width: var(--webm-width-wide);
+  }
+  .webm-container:where([data-width='content']) {
+    --webm-container-width: var(--webm-width-content);
+  }
+  .webm-container:where([data-width='narrow']) {
+    --webm-container-width: var(--webm-width-narrow);
+  }
+  .webm-container:where([data-width='text']) {
+    --webm-container-width: var(--webm-width-text);
+  }
+
+  /* --- stack: vertical rhythm ---------------------------------------------- */
+
+  .webm-stack {
+    display: flex;
+    flex-direction: column;
+    gap: var(--webm-stack-gap, var(--webm-space-md));
+  }
+
+  .webm-stack:where([data-gap='2xs']) {
+    --webm-stack-gap: var(--webm-space-2xs);
+  }
+  .webm-stack:where([data-gap='xs']) {
+    --webm-stack-gap: var(--webm-space-xs);
+  }
+  .webm-stack:where([data-gap='sm']) {
+    --webm-stack-gap: var(--webm-space-sm);
+  }
+  .webm-stack:where([data-gap='lg']) {
+    --webm-stack-gap: var(--webm-space-lg);
+  }
+  .webm-stack:where([data-gap='xl']) {
+    --webm-stack-gap: var(--webm-space-xl);
+  }
+
+  /* --- cluster: horizontal group that wraps -------------------------------- */
+
+  .webm-cluster {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: var(--webm-cluster-gap, var(--webm-space-sm));
+  }
+
+  .webm-cluster:where([data-justify='between']) {
+    justify-content: space-between;
+  }
+  .webm-cluster:where([data-justify='center']) {
+    justify-content: center;
+  }
+  .webm-cluster:where([data-justify='end']) {
+    justify-content: flex-end;
+  }
+
+  .webm-cluster:where([data-gap='2xs']) {
+    --webm-cluster-gap: var(--webm-space-2xs);
+  }
+  .webm-cluster:where([data-gap='xs']) {
+    --webm-cluster-gap: var(--webm-space-xs);
+  }
+  .webm-cluster:where([data-gap='md']) {
+    --webm-cluster-gap: var(--webm-space-md);
+  }
+  .webm-cluster:where([data-gap='lg']) {
+    --webm-cluster-gap: var(--webm-space-lg);
+  }
+
+  /* --- grid: auto-fitting columns ------------------------------------------ */
+
+  /* No breakpoints — the grid reflows on available width, not viewport width. */
+  .webm-grid {
+    display: grid;
+    gap: var(--webm-grid-gap, var(--webm-space-lg));
+    grid-template-columns: repeat(auto-fit, minmax(min(var(--webm-grid-min, 18rem), 100%), 1fr));
+  }
+
+  .webm-grid:where([data-columns='2']) {
+    --webm-grid-min: 24rem;
+  }
+  .webm-grid:where([data-columns='3']) {
+    --webm-grid-min: 18rem;
+  }
+  .webm-grid:where([data-columns='4']) {
+    --webm-grid-min: 14rem;
+  }
+
+  .webm-grid:where([data-gap='sm']) {
+    --webm-grid-gap: var(--webm-space-sm);
+  }
+  .webm-grid:where([data-gap='md']) {
+    --webm-grid-gap: var(--webm-space-md);
+  }
+  .webm-grid:where([data-gap='xl']) {
+    --webm-grid-gap: var(--webm-space-xl);
+  }
+
+  /* --- breakout grid (opt-in, editorial pages) ----------------------------- */
+
+  /*
+   * Named grid lines let a child pick its own width with one declaration:
+   *   <div class="webm-breakout">
+   *     <p>…</p>                        <- defaults to `content`
+   *     <figure data-span="full">…</figure>
+   *   </div>
+   */
+  .webm-breakout {
+    display: grid;
+    grid-template-columns:
+      [full-start] minmax(var(--webm-gutter), 1fr)
+      [wide-start] minmax(0, calc((var(--webm-width-max) - var(--webm-width-wide)) / 2))
+      [content-start] minmax(0, calc((var(--webm-width-wide) - var(--webm-width-content)) / 2))
+      [text-start] min(100% - (var(--webm-gutter) * 2), var(--webm-width-text)) [text-end]
+      minmax(0, calc((var(--webm-width-wide) - var(--webm-width-content)) / 2))
+      [content-end] minmax(0, calc((var(--webm-width-max) - var(--webm-width-wide)) / 2))
+      [wide-end] minmax(var(--webm-gutter), 1fr) [full-end];
+  }
+
+  .webm-breakout > * {
+    grid-column: content;
+  }
+  .webm-breakout > :where([data-span='text']) {
+    grid-column: text;
+  }
+  .webm-breakout > :where([data-span='wide']) {
+    grid-column: wide;
+  }
+  .webm-breakout > :where([data-span='full']) {
+    grid-column: full;
+  }
+
+  /* --- media bleed: image edge-to-edge behind constrained content ---------- */
+
+  .webm-section:where([data-media]) {
+    position: relative;
+    isolation: isolate;
+    padding-block: var(--webm-section-lg);
+    color: var(--webm-text-inverse);
+  }
+
+  .webm-section__bleed {
+    position: absolute;
+    inset: 0;
+    z-index: var(--webm-z-below);
+    inline-size: 100%;
+    block-size: 100%;
+    object-fit: cover;
+  }
+
+  /* Scrim over the bleed image, so overlaid text keeps its contrast ratio. */
+  .webm-section:where([data-media])::before {
+    content: '';
+    position: absolute;
+    inset: 0;
+    z-index: var(--webm-z-below);
+    background-color: color-mix(
+      in oklch,
+      var(--webm-base-900) var(--webm-media-scrim, 55%),
+      transparent
+    );
+  }
+
+  .webm-section:where([data-scrim='light']) {
+    --webm-media-scrim: 30%;
+  }
+  .webm-section:where([data-scrim='heavy']) {
+    --webm-media-scrim: 75%;
+  }
+  .webm-section:where([data-scrim='none']) {
+    --webm-media-scrim: 0%;
+  }
+}