content: add CSS variables as consistency constraints guide#66
Merged
Conversation
Document why ad-hoc spacing/color/border values drift across iterations and how a variable-driven design system turns consistency into a constraint the code enforces. The guide was prompted by multiple rounds of spacing oscillation on this site's content pages, which memory captured but the handbook did not yet carry as shareable guidance. Layer 1 content: universal principles with a reference to GitHub Markdown CSS as a typography baseline, CSS Custom Properties (MDN), and the W3C Design Tokens Community Group. No project-specific file paths or scripts appear in the narrative. Also mark the item completed in ROADMAP under Next. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
wilsonwangdev
added a commit
that referenced
this pull request
May 7, 2026
…ules (#67) Add three rules to AGENTS.md Quality Baseline that encode the content-page UX lessons captured in session memory (`feedback_content_page_ux.md`). ## Changes Three new bullets in the Quality Baseline section: - Spacing, border-width, and colors must reference `--space-*`, `--border-*`, and color tokens. Bare `rem`/`px` literals for margin, padding, gap, or border-width are a review finding. Points at the new `content/guides/css-variable-consistency/` guide for rationale. - Adding or changing a divider-style border requires auditing all existing dividers in the file as a set. Mixed widths (1px vs 2px) or mixed color tokens (`--border` vs `--border-bright`) count as inconsistency. - Dark-theme pages must inline critical `background`/`color` CSS in `<head>` with a light-mode media-query fallback to prevent FOUC. ## Why The frontend-interaction-review skill's new Visual consistency group (PR #65) already encodes these rules. Mirroring them in the Quality Baseline makes them discoverable during pre-work without requiring the agent to open the skill file first — most pre-work checks live in AGENTS.md today. ## Relation to other open PRs - PR #65 adds the skill-level version of the same rules. - PR #66 adds the Layer 1 rationale guide. - This PR (#?) adds the project-specific baseline enforcement. Each lives in a different file; no rebase coordination needed. ## Tested `npm run build` succeeds — 26 pages generated. The added guide reference (`content/guides/css-variable-consistency/en.md`) is correct relative to merged state once PR #66 lands. Co-authored-by: Claude Opus 4.7 (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.
Document why ad-hoc spacing/color/border values drift across agent-assisted iteration, and how a variable-driven design system turns consistency from a memory problem into a constraint the code enforces.
Changes
Guide contents
--space-*,--border-width-*, etc.), forbid bare numbers.package.json).Why
Content-page UX work this cycle spent several iterations oscillating on spacing because each adjustment was a bare number. The lesson was captured in session memory (
feedback_content_page_ux.md) but had not yet become shareable handbook content. Formalizing it here turns the memory into Layer 1 guidance.Sources
Per the traceability rule: all external claims link to primary sources — GitHub Markdown CSS, MDN on CSS Custom Properties, W3C Design Tokens Community Group.
Tested
npm run buildsucceeds — 28 pages generated (2 new). Both language pages appear insitemap.md.