remarque-tokens 0.2.0

package/AGENT_RULES.md

@@ -0,0 +1,218 @@
+# Remarque — Agent Rules
+
+**This document is the implementation contract for any agent (AI or human) building with the Remarque design system.**
+
+Read `REMARQUE.md` first for the full system specification. This file tells you *how to build*, not *what the system is*.
+
+---
+
+## Build Order
+
+Execute in this exact order. Do not skip steps. Do not reorder.
+
+1. **Load tokens.** Import `tokens.css` and configure `tailwind.config.js` with Remarque's font families and extended theme values. Verify fonts load correctly.
+
+2. **Set up global typography.** Apply display, title, section, body, meta, and prose classes. Verify the type scale renders correctly at mobile and desktop widths.
+
+3. **Build the layout shell.** Header, content container (with constrained max-widths), and footer. The shell must enforce reading widths — content should never run full-width on large screens.
+
+4. **Implement prose styling.** Article body text, headings within prose, blockquotes, lists, inline code, links. This is the core of Remarque — get it right before touching anything else.
+
+5. **Implement metadata components.** Mono-styled date, reading time, tags, and status labels.
+
+6. **Build navigation and footer.** Quiet, minimal. Navigation is functional, not decorative.
+
+7. **Only then** build supplementary UI: buttons, tags, cards (if justified), code blocks, tables.
+
+8. **Validate readability on mobile** before adding any visual polish.
+
+9. **Verify every page conforms** to one of the four archetypes (Essay, Project Dossier, Notebook, Landing).
+
+**Why this order matters:** Most agents build polished components first and bolt on typography later. That produces the exact aesthetic Remarque exists to prevent. Typography and prose are the foundation. Everything else is furniture.
+
+---
+
+## Non-Negotiable Rules
+
+These are not guidelines. Agents must follow them literally.
+
+### Token Tiers
+
+- NEVER change a value in `tokens-core.css` (or its tokens' values anywhere) — core tokens are Remarque's identity; changing them means the project has forked the system
+- Site personalization happens ONLY by overriding `tokens-palette.css` tokens (font slots from the approved pairings, colors, accent, `--content-reading` per the measure table) in a stylesheet loaded after the tokens
+- After ANY palette change, run the audit and fix every failure before shipping — `npm run audit` inside this repo; `npx remarque-audit --palette <file> --src <dir>` in a consumer project (the npm script only exists here)
+
+### Typography
+
+- Body text is never smaller than `--text-body` (17px / 1.0625rem)
+- Prose columns never exceed `--content-reading` (46rem)
+- Display/title text always uses `--font-display` (Newsreader)
+- Body text always uses `--font-body` (Inter)
+- Mono text is *only* for: metadata, code, labels, timestamps, technical accents
+- Line height for body text is `--leading-body` (1.75) — never less
+
+### Layout
+
+- No page shows more than 3 content sections above the fold
+- The first screen contains only: title, metadata, and the start of content
+- Top padding before the main heading is at least `--space-9` (6rem)
+- The site uses a **single centered column** layout: BaseLayout constrains all content to `content-standard` (72rem) centered. Individual pages do NOT set their own outer width constraints.
+- Within the centered column, use `.content-reading` for prose-width sections (46rem, auto-centered within the 72rem column)
+- Do NOT use Tailwind's `max-w-reading` or `max-w-standard` on page sections — these only set max-width without centering. Use the CSS classes `.content-reading` / `.content-standard` instead, which include `margin-inline: auto`
+- Code blocks (`<pre>`) inherit the width of their parent container — no special wrapping needed when the parent is already constrained
+
+### Color
+
+- Accent color is used for exactly two things: inline links and one interactive element per viewport
+- Dark mode is not an inverted light mode — it must be independently tuned for readability
+- Background colors use `--color-bg`, never pure white (#fff) or pure black (#000)
+
+### Components
+
+- No component should be visually louder than the content it contains
+- Borders use `--color-border` at 1px — never thicker, never drop shadows as replacements
+- `--color-border` is decorative-only (below the 3:1 non-text minimum by design). Boundaries of interactive elements (inputs, dialogs, active states) use `--color-border-bold`, which meets WCAG 1.4.11
+- Border radius never exceeds `--radius-md` (0.5rem / 8px)
+- Buttons are quiet: text-only or subtle bordered. Never filled/solid as default.
+
+### Motion
+
+- Motion is permitted *only* on: hover states, focus rings, theme transitions
+- Duration is `--motion-fast` (120ms) for micro-interactions, `--motion-normal` (180ms) for transitions
+- No scroll-triggered, entrance, staggered, or parallax animations. Ever.
+- All motion must respect `prefers-reduced-motion` — always use the duration tokens (tokens.css zeroes them under reduced motion); never hardcode durations
+
+### Images
+
+- Images stay within `--content-reading` width (diagrams may use `--content-standard`)
+- Images get a 1px `--color-border` border, never shadows
+- Captions use `--font-mono` at `--text-meta` size
+- No decorative images. Every image serves the content.
+
+---
+
+## Decision Protocol
+
+When you face a design choice not explicitly covered above, apply these filters in order:
+
+1. **Is it more readable?** → Choose that.
+2. **Is it more typographically disciplined?** → Choose that.
+3. **Is it quieter?** → Choose that.
+4. **Is it more tokenized/reusable?** → Choose that.
+5. **Does it have less visual noise?** → Choose that.
+
+If you are still unsure, choose the option that looks more like a well-typeset book and less like a web application.
+
+---
+
+## Disallowed Patterns
+
+Do not introduce any of the following unless the project owner explicitly requests them:
+
+- Material Design visual language (elevation, ripple, FAB)
+- Large decorative gradients
+- Glassmorphism / frosted glass
+- Card grids as primary layout
+- Over-rounded corners (border-radius > 0.5rem)
+- "Friendly SaaS" visual language
+- Flashy or attention-seeking motion
+- Dense admin/dashboard layouts
+- Full-width prose on screens wider than 768px
+- Hero images or banners
+- Multiple CTAs on a single page
+- Feature comparison grids
+- Newsletter popups or modals
+- Hamburger menus on desktop
+- Sticky headers that consume vertical space
+- Social share buttons in content areas
+- Pill-shaped tag badges (use plain mono text)
+- Skeleton loading screens (use a simple spinner or nothing)
+
+---
+
+## File Structure Convention
+
+```
+project/
+├── fonts.css                 # Self-hosted @font-face declarations (import before tokens)
+├── tokens.css                # Aggregator — imports the two tiers below
+├── tokens-core.css           # CORE tier: type scale, spacing, widths, radius, motion, prose machinery. NEVER override
+├── tokens-palette.css        # PALETTE tier: font slots, colors, accent, reading measure. Override freely, then run the audit
+├── tailwind.config.js        # Tailwind v3 ONLY — v4 projects skip this and use an @theme block (see site/src/styles/globals.css)
+├── public/
+│   └── fonts/                # Self-hosted woff2 fonts (Inter, Newsreader, JetBrains Mono)
+├── styles/
+│   ├── globals.css           # @import "tailwindcss"; @import "./tokens.css"; @font-face declarations
+│   ├── prose.css             # Article/essay body text styling (or use .remarque-prose from tokens.css)
+│   └── components.css        # Component-specific styles (minimal)
+├── components/
+│   ├── Layout.{jsx,astro}    # Layout shell (header + content + footer + skip-link + theme toggle)
+│   ├── Nav.{jsx,astro}       # Navigation (content pages + design system docs)
+│   ├── Footer.{jsx,astro}    # Footer
+│   ├── Meta.{jsx,astro}      # Metadata row component
+│   └── Prose.{jsx,astro}     # Prose wrapper (<div class="remarque-prose content-reading">)
+└── pages/
+    ├── index                 # Landing archetype
+    ├── writing/[slug]        # Essay archetype
+    ├── projects/[slug]       # Project Dossier archetype
+    └── notes                 # Notebook archetype
+```
+
+### Implementation Pitfalls (learned from reference implementation)
+
+1. **Tailwind spacing collision:** Never map Remarque's `--space-N` values onto Tailwind's default numeric spacing keys — in v4 `@theme` that means no `--spacing-9`…`--spacing-12`, and in the v3 config no `spacing: { "5"…"12" }` overrides — or `mt-12` produces 192px instead of 48px. Both shipped artifacts namespace instead: the v3 config exposes `mt-remarque-9` etc., the reference v4 `@theme` uses `--spacing-remarque-N`. Use those, or `var(--space-N)` in arbitrary values.
+
+2. **Prose alignment:** The essay header and prose body must BOTH use centered max-width (`max-w-reading mx-auto`) to prevent misalignment. The `.content-reading` class auto-centers; match headers with `mx-auto`.
+
+3. **Dark mode specificity:** Define `[data-theme="light"]` and `[data-theme="dark"]` overrides in addition to the `:root` defaults. Without an explicit light override, users with `prefers-color-scheme: dark` cannot toggle to light mode.
+
+4. **Self-hosted fonts:** Replace the Google Fonts CDN link with self-hosted woff2 files + `@font-face` declarations. Use `font-display: swap` and `<link rel="preload">` for performance.
+
+5. **GitHub Pages base path:** When deploying to a subpath (e.g., `/remarque/`), all internal links must use a base URL helper (Astro: `import.meta.env.BASE_URL`). Set `base` in your framework config.
+
+6. **String-form @import only:** Always write `@import './tokens.css';` (string form). Tailwind v4 / Lightning CSS silently DROPS `@import url(...)` for local files — the build succeeds while the entire token cascade vanishes from the output. Verify the built CSS contains `.remarque-prose` after changing imports.
+
+---
+
+## Quality Checklist
+
+Before considering any implementation complete, verify:
+
+- [ ] Fonts load: Newsreader for display, Inter for body, JetBrains Mono for meta
+- [ ] Fonts are self-hosted (no Google CDN requests in network tab)
+- [ ] Body text is ≥17px on all viewports
+- [ ] Prose column is ≤46rem on desktop
+- [ ] Prose header and body are aligned (both centered with `mx-auto` or both left-aligned)
+- [ ] Line height for body text is 1.75
+- [ ] Dark mode is readable and independently tuned (not just inverted)
+- [ ] Theme toggle works in both directions (light→dark AND dark→light)
+- [ ] No page has more than 3 content sections above the fold
+- [ ] Top padding before main heading is ≥6rem
+- [ ] Accent color appears in ≤2 roles per viewport
+- [ ] No scroll-triggered or entrance animations exist
+- [ ] Every image has a 1px border and mono caption
+- [ ] Every page maps to an archetype (Essay, Dossier, Notebook, Landing)
+- [ ] Mobile version is roomy — not a compressed desktop layout
+- [ ] Mobile nav links have ≥44px touch targets
+- [ ] No pure white or pure black backgrounds
+- [ ] `npm run audit` passes (contrast, gamut, font floors, hardcoded colors)
+- [ ] Muted text placed on `--color-surface` still meets 4.5:1 (check the surface pairing, not just bg)
+- [ ] All transitions use the motion duration tokens (reduced-motion support depends on it)
+- [ ] Skip-to-content link present and functional
+- [ ] OG meta tags present (og:title, og:description, og:image)
+- [ ] `<html lang="en">` attribute set
+- [ ] The site looks more like a book than a web app
+- [ ] Tailwind spacing utilities (`mt-12`, `pt-8`) produce expected values (not overridden by `@theme`)
+
+---
+
+## How to Reference This System
+
+In prompts, issues, or agent instructions, use:
+
+```
+Build this page using the Remarque design system.
+See: REMARQUE.md for specification, AGENT_RULES.md for implementation contract, tokens.css for design tokens.
+```
+
+Agents should load all three files before beginning work.

package/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to `remarque-tokens` are documented here. Token value
+changes always state the design rationale — downstream sites pin against
+these entries when syncing.
+
+## 0.2.0 — 2026-07-20
+
+First published release. Everything below is relative to the unpublished
+`0.1.0` files that early adopters copied by hand.
+
+### Added
+- **Two-tier token architecture** (#47): `tokens-core.css` (immutable
+  identity — type scale, spacing, widths, radius, motion, prose
+  machinery) and `tokens-palette.css` (sanctioned personalization —
+  font slots, colors, accent, `--content-reading` measure). `tokens.css`
+  remains a backwards-compatible aggregator. Subpath exports:
+  `remarque-tokens/core`, `remarque-tokens/palette`.
+- **`remarque-audit`** CLI (#28): enforces the spec's checklist —
+  WCAG 2.x contrast (OKLCH → sRGB → relative luminance), sRGB gamut,
+  13px font floor, no hardcoded colors. `npx remarque-audit --palette
+  <file> --src <dir>`.
+- **`fonts.css` + `fonts/`** (#40): self-hosted latin woff2 subsets for
+  all three slots, including true Inter italic. The Google Fonts CDN
+  `@import` is gone.
+- `prefers-reduced-motion` support (#45): the motion duration tokens
+  zero out under reduced motion.
+- Spec sections: Token Tiers, Font Slots with approved pairings,
+  Measure Compensation table, accent-hue derivation recipe.
+
+### Changed
+- **Contrast fixes** (#42), all computed and audit-enforced:
+  - light `--color-fg-muted` 0.45 → **0.43** L (7.55:1, meets the spec's own AAA line)
+  - light `--color-muted` 0.55 → **0.54** L; dark 0.58 → **0.60** L (≥4.5:1 on bg *and* surface)
+  - `--color-border-bold` light 0.78 → **0.62** L, dark 0.35 → **0.50** L (≥3:1, WCAG 1.4.11)
+  - `--color-border` documented **decorative-only** (below 3:1 by design;
+    functional boundaries use `border-bold`)
+- **Gamut fixes:** light `--color-accent-hover` chroma 0.14 → **0.11**,
+  `--color-accent-subtle` 0.03 → **0.02** — previous values were outside
+  sRGB and browser-clipped.
+- `tailwind.config.js` (#41): spacing namespaced as `remarque-N`
+  (Tailwind's default numeric scale no longer overridden — `mt-12` is
+  3rem again), `darkMode` keyed to `[data-theme="dark"]`, dead
+  typography-plugin block removed. Tailwind v3 only; v4 projects write
+  an `@theme` block.
+
+### Removed
+- `--weight-light`, `--space-px`, `--space-0` (defined but never
+  consumed anywhere).
+
+### Known limitations
+- Import the token files with **string-form** `@import './tokens.css'`
+  only — Tailwind v4 / Lightning CSS silently drops `@import url(...)`
+  for local files (AGENT_RULES.md Pitfall #6).
+- No Tailwind v4 `@theme` file is shipped yet (#48).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 William Zujkowski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# Remarque
+
+**A typography-first design system for editorial, technical, and personal web projects.**
+
+[Live Demo](https://williamzujkowski.github.io/remarque/) | [Type Specimen](https://williamzujkowski.github.io/remarque/specimen/) | [Design Tokens](https://williamzujkowski.github.io/remarque/tokens/) | [Get Started](https://williamzujkowski.github.io/remarque/start/)
+
+---
+
+## Why Remarque?
+
+Most developer sites inherit the visual language of SaaS dashboards or component-library defaults. Remarque is the antidote: a system rooted in book typography, editorial design, and the quiet confidence of a well-made publication.
+
+**What makes it different:**
+
+- **Typography is the interface** — not color, not illustration, not animation. Three fonts (Newsreader, Inter, JetBrains Mono), each with a strict role.
+- **17px minimum body text** — one pixel above the industry default. The difference in reading comfort is immediate.
+- **46rem reading column** — derived from the typographic standard of 45-75 characters per line.
+- **OKLCH color space** — perceptually uniform. A lightness of 0.50 actually looks mid-brightness.
+- **Self-hosted fonts** — no Google CDN dependency. Strict CSP. GDPR-compliant.
+- **AI-native** — designed to be consumed by Claude Code, Cursor, Copilot, and other AI coding tools with zero aesthetic drift.
+
+## Install
+
+Copy `fonts.css`, `tokens.css`, `tokens-core.css`, `tokens-palette.css`, and the `fonts/` directory into your project (`tokens.css` is an aggregator that imports the two tier files), then:
+
+```css
+@import 'fonts.css';
+@import 'tokens.css';
+```
+
+Tailwind v3 projects can additionally copy `tailwind.config.js`. Tailwind v4 projects skip the config and write an `@theme` block from the token values (see `site/src/styles/globals.css` for the reference).
+
+> **npm:** `remarque-tokens` is not yet published to the registry — the publish pipeline (provenance, semver, changelog) is tracked in [#46](https://github.com/williamzujkowski/remarque/issues/46) and [#48](https://github.com/williamzujkowski/remarque/issues/48). Until then, the copy path above (or `npm install github:williamzujkowski/remarque`) is the supported install.
+
+## For AI Agents
+
+Remarque includes a machine-readable implementation contract. When prompting any AI coding tool:
+
+```
+Build this page using the Remarque design system.
+See: REMARQUE.md for specification, AGENT_RULES.md for implementation contract, tokens.css for design tokens.
+```
+
+The agent rules define build order, non-negotiable rules, disallowed patterns, and a quality checklist. Every decision is specified — agents don't need to guess.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `REMARQUE.md` | Full system specification — philosophy, visual rules, page archetypes, acceptance criteria |
+| `AGENT_RULES.md` | Implementation contract — build order, non-negotiables, pitfalls, quality checklist |
+| `tokens.css` | Aggregator importing the two token tiers below |
+| `tokens-core.css` | Core tier — type scale, spacing, widths, radius, motion, prose styling. Never overridden |
+| `tokens-palette.css` | Palette tier — font slots, colors, accent, reading measure. The sanctioned personalization surface |
+| `scripts/audit.mjs` | `npm run audit` — enforces the spec's contrast/gamut/font-floor/no-hardcoded-color checklist |
+| `fonts.css` + `fonts/` | Self-hosted @font-face declarations and woff2 files (no CDN requests) |
+| `tailwind.config.js` | Tailwind CSS **v3** configuration (v4 projects use an `@theme` block instead) |
+| `package.json` | npm package manifest for `remarque-tokens` |
+
+## Three-Font System
+
+| Role | Font | Usage |
+|------|------|-------|
+| **Display** | Newsreader | Page titles, hero headings, article titles. Never for body copy. |
+| **Body** | Inter | Body text, UI labels, navigation, buttons. The workhorse. |
+| **Mono** | JetBrains Mono | Metadata, code, timestamps, labels. Never for headings. |
+
+## Page Archetypes
+
+Every page conforms to one of four archetypes:
+
+- **Essay** — long-form writing with serif title, mono metadata, narrow reading column
+- **Project Dossier** — structured project page with metadata block and architecture section
+- **Notebook** — short-form notes with mono timestamps, no cards
+- **Landing** — identity statement, content navigation, generous whitespace
+
+See the [live demo](https://williamzujkowski.github.io/remarque/) for all four archetypes in action.
+
+## Design Decisions
+
+| Decision | Value | Why |
+|----------|-------|-----|
+| Body size | 17px | Measurably improves reading comfort over 16px default |
+| Line height | 1.75 | Generous — this is what makes prose readable |
+| Reading width | 46rem | ~70 chars/line at 17px Inter. Upper end of comfortable range for technical content |
+| Color space | OKLCH | Perceptual uniformity. Consistent across hues without manual tuning |
+| Top padding | 6rem min | The breathing room that says "this is editorial, not a dashboard" |
+| Border radius | 0.5rem max | Restrained. No "friendly SaaS" over-rounding |
+| Motion | 120ms/180ms | Hover and theme transitions only. No scroll-triggered, entrance, or staggered animations |
+
+## Named For
+
+In fine art printmaking, a *remarque* is a small original drawing made by the artist in the margin of a proof print. Found only in limited editions, it is the mark that says: this was made by someone specific, with intention.
+
+## License
+
+MIT