docs(authoring-contract): add viewport height budget and concrete via direction contract - #363
docs(authoring-contract): add viewport height budget and concrete via direction contract#363ljcjeans-dev wants to merge 1 commit into
Conversation
… direction contract
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Advanced Run ID: 📒 Files selected for processing (1)
Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review. 📝 SummarySummary
Compatibility impact
Validation
WalkthroughChangesAuthoring contract
Priority: ⬇️ Low — Defer this documentation-only contract update because it changes no code, schemas, defaults, acceptance rules, generated artifacts, or existing behavior. Estimated code review effort: 1 (Trivial) | ~2 minutes Merge Risk: ⚪ Minimal · up to This updates authoring guidance for route orientation and first-screen viewport budgeting without changing runtime behavior or data handling. No current merge-blocking risk remains. 🚥 Pre-merge checks | ❌ 2❌ Failed checks (2 warnings)
Full details: Contribution ScopeExplanation The PR has a focused documentation scope and explains the problem, rationale, compatibility impact, and non-applicable visual/runtime checks. However, it changes a published Skill reference without updating its generated archive. The exact base-to-head diff changes only Full details: Validation EvidenceExplanation The changed file is a packaged Skill instruction, not repository-only prose. CONTRIBUTING.md requires Resolution Run Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Problem and value
Current-main trigger: a candidate that passes
validate --quality showcasewith 0 errors / 0 warnings can still overflow the 1440×900 first screen invisual-check. The docs describe the goal qualitatively ("over-compressed Y layout", "vertical rhythm") but give no quantitative budget, so an author rediscovers the page-height arithmetic by trial and error after the spec is already frozen. Separately, the via direction contract is enforced byclean-flow/endpoint-side-directionbut stated only abstractly ("a side is a direction contract"), so the exact constraint onvia[0]coordinates is learnable only by triggering the error.Intended outcome: an author can budget the viewport height at authoring time and write compliant
viawaypoints on the first try.Evidence from a real authoring session on 2.16: official example
web-app-rendered.htmlat viewBox 1080×588 (ratio 1.84) passes all four viewports, while my candidate at 1225×648 (ratio 1.89) overflows 1440×900 by 79px. A higher ratio overflowing while a lower one passes proves "keep the ratio above a threshold" is the wrong mental model; the determinant is absolute rendered height (viewer chrome ~51px + 930px reader-width × viewBoxH/viewBoxW + cards). Tightening card copy recovered 34px; stretching node x-coordinates (viewBox 1225→1315) recovered the remaining 11px.Approach: docs-only — one new subsection and one bullet extension (below). Narrow documentation correction; per CONTRIBUTING "Choose the right path", no separate planning issue needed.
Stability impact
Tests run
main@ 1072200. Candidate: this branch (1 commit).archify doctorunaffected (docs not loaded by the CLI).Visual evidence
Not applicable — documentation-only change; no rendering path touched.
Generated artifacts
None; no generated files reference
references/authoring-contract.mdcontent.