rule: codify design intent for visual changes#74
Merged
Conversation
Add rules/design-intent.md capturing the project's stated visual constraints — tone (editorial reference, not marketing), three-font type system, brightness-not-hue accent, spacing scale as the only legal source for margin/padding/gap/border-width, density at wide viewports, and homepage section order (Header → Timeline → Quick Start → Content). AGENTS.md gains a one-line pointer in the Quality Baseline so any future visual change reviews the rule before silently overriding it. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
This was referenced Jun 1, 2026
wilsonwangdev
added a commit
that referenced
this pull request
Jun 1, 2026
## Summary Two coordinated changes that implement [rules/design-intent.md](rules/design-intent.md) §4 (spacing scale) and §6 (homepage section order). Depends on #74 conceptually — the rule explains the why for every change in this PR. ## CSS — spacing scale (design-intent §4) - Add `--space-2xl` (3rem) and `--space-3xl` (4.5rem) to the scale - Replace ~30 bare rem literals (margin, padding, gap, border) with `--space-*` tokens — the scale is now the only legal source for those properties, matching the rule's stated constraint - Section-level rhythm uses `--space-3xl`, content-level uses `--space-2xl`, inline uses `--space-md` and below ## CSS — density and typography (design-intent §5) - Add a `min-width: 1100px` breakpoint that widens `--max-w` to `64rem` and bumps the hero `h1` to `3.2rem`. Wide viewports now widen content rather than centering more padding — handbook is for reading throughput, not breathing room. - Hero `h1` shrinks `3rem → 2.8rem` to read closer to Stripe Press / Linear blog reference points; tagline grows `0.85rem → 0.9rem` with looser letter-spacing for legibility. ## Template — section order (design-intent §6) - Move `{{timeline}}` before `.quickstart` in [build/templates/index.html](build/templates/index.html) so the homepage reads **Header → Timeline → Quick Start → Content**. - Verified at 1200×675 X-card crop the hero now leads with the timeline (the story) instead of the prompt block (the action). This fixes the marketing-site feel called out on 2026-05-14 and was the trigger for codifying §6 in the rule. ## Tested - `npm run build` passes, 36 pages emitted, no warnings - Manual review of all `--space-*` substitutions — rhythm preserved at 1.5rem→`--space-lg` and 1rem→`--space-md` boundaries - Wide-viewport and mobile breakpoints both visually checked ## Quality baseline impact No expected impact on Lighthouse: zero new render-blocking resources, no new fonts, no contrast changes (`--muted` and `--accent` untouched), no new layout shifts. ## Notes for reviewer - The `padding-right: 4rem` on `.prompt-block pre` is intentionally **not** tokenized — it's an asymmetric reservation for the absolute-positioned copy button, not a rhythm value. Worth flagging as a design-intent §4 edge case if reviewers think otherwise. - `.section li a` font-size goes `1.15rem → 1.1rem` — small adjustment for visual balance with the new tagline size. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
wilsonwangdev
added a commit
that referenced
this pull request
Jun 1, 2026
## Summary Adds [build/screenshot.mjs](build/screenshot.mjs) and an `npm run screenshot` command that captures the local dev server across four viewports and four representative pages — used as a manual review aid for visual changes. | Viewport | Size | Purpose | |---|---|---| | `x-card` | 1200×675 @2x | X/Twitter share crop | | `og-image` | 1200×630 @2x | OpenGraph share image | | `desktop` | 1440×900 @2x | Standard desktop preview | | `mobile` | 390×844 @3x | iPhone preview | Pages: `/en/`, `/zh/`, `/en/concepts/harness-engineering/`, `/en/guides/skills-ecosystem/`. ## Why The homepage section order was reverted on 2026-05-14 specifically because the X-card crop showed only the prompt block — without the timeline, the hero gave the wrong first impression. That signal came from a one-off manual screenshot. Codifying it as a script means the next visual change can run the same check in one command. This complements [rules/design-intent.md](rules/design-intent.md) (PR #74) — the rule states the intent, this script gives reviewers a concrete way to verify it. ## Implementation choices - **`puppeteer-core` + system Chrome** instead of full `puppeteer`. The full package downloads ~150 MB of bundled Chromium on every install; `puppeteer-core` reuses the user's installed Chrome / Chromium. Falls back to `CHROME_PATH` env var if auto-detection fails. - **Output to `assets/screenshots/`**, gitignored. Screenshots are a local-only review artifact, not committed. - **Caret-pinned dep version** matches the existing `husky` style in `package.json`. ## Tested - `npm install` succeeds; `package-lock.json` updated for `puppeteer-core` transitive deps (lockfile diff is large but is entirely puppeteer's dependency closure — no typosquatting candidates spotted). - `npm run screenshot` runs against a local `npm run dev` instance and produces 16 PNGs under `assets/screenshots/`. - Script exits cleanly; no Chromium processes left orphaned. ## Notes for reviewer - The lockfile diff (~1000 lines) is unavoidable for this kind of dep addition. All adds are in `node_modules/puppeteer-core/**` and its declared dependencies. - `.claude/worktrees/` is intentionally **not** added to `.gitignore` here — that's agent-runtime state, better handled in a global gitignore. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
wilsonwangdev
added a commit
that referenced
this pull request
Jun 1, 2026
) (#77) ## Summary Archives a 2026-05-08 investigation that had been sitting uncommitted in a feature worktree until today, and closes the loop with the fix that just shipped. [journal/2026-05-08-wide-viewport-whitespace.md](journal/2026-05-08-wide-viewport-whitespace.md) records: - **What happened** — capturing 1280×720 social-launch screenshots revealed ~35% horizontal whitespace because the site had exactly one breakpoint (`max-width: 640px`) and a fixed `--max-w: 52rem` - **Root cause** — review processes (Lighthouse, frontend-interaction-review skill) optimized for correctness, not visual density at wide viewports - **Resolution** — closed by #76, which added `@media (min-width: 1100px)` widening `--max-w` to `64rem`. The two alternative options (2-col layout, decorative frame) were rejected because they conflict with `rules/design-intent.md` §5 (wide viewports widen content, not whitespace or chrome) - **Prevention** — ROADMAP item to add a viewport-density check to the frontend-interaction-review skill's next revision [ROADMAP.md](ROADMAP.md) gains three matching `[x]` rows in **Now** for #74 / #75 / #76. [.gitignore](.gitignore) adds `assets/social/` — launch screenshots are local promotional artifacts. The first batch (May 8) is staying on disk but won't be committed. ## Why this matters The journal entry is exactly the "failures captured for agent self-evolution" use case in CLAUDE.md. Without committing it, the institutional memory of *why* PR #76 added that specific breakpoint at 1100px (and not, say, 1280px or 1440px) would have been lost. This PR makes the chain `1280px screenshot reveals issue → root cause → option list → chosen fix → rule §5` discoverable from a single file. ## Tested Lint-only / docs-only changes. No build impact. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds rules/design-intent.md — the project's stated visual constraints, in writing — so future agent-driven CSS / template / typography changes have a baseline to check against rather than re-deriving aesthetics each time.
Six intent statements:
--space-*scale is the only legal source for margin/padding/gap/border-widthAGENTS.md gains a one-line pointer in the Quality Baseline section so the rule is surfaced before any visual change.
Why now
Recent visual iterations kept rediscovering the same constraints from scratch (spacing literals, accent hue, section order). Codifying the intent prevents silent overrides and gives PR review an explicit reference.
Tested
rules/follows the existing rule frontmatter shape (name,type,severity,verified,trigger).