Skip to content

docs(authoring-contract): add viewport height budget and concrete via direction contract - #363

Open
ljcjeans-dev wants to merge 1 commit into
tt-a1i:mainfrom
ljcjeans-dev:pr1-viewport-budget
Open

docs(authoring-contract): add viewport height budget and concrete via direction contract#363
ljcjeans-dev wants to merge 1 commit into
tt-a1i:mainfrom
ljcjeans-dev:pr1-viewport-budget

Conversation

@ljcjeans-dev

Copy link
Copy Markdown

Problem and value

Current-main trigger: a candidate that passes validate --quality showcase with 0 errors / 0 warnings can still overflow the 1440×900 first screen in visual-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 by clean-flow/endpoint-side-direction but stated only abstractly ("a side is a direction contract"), so the exact constraint on via[0] coordinates is learnable only by triggering the error.

Intended outcome: an author can budget the viewport height at authoring time and write compliant via waypoints on the first try.

Evidence from a real authoring session on 2.16: official example web-app-rendered.html at 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

  • Impact class: documentation only. No code, schema, defaults, or acceptance rules changed.
  • Existing behavior preserved: all existing text unchanged except the one direction-contract bullet, which is strictly extended (original sentence retained verbatim).
  • No unrelated changes: confirmed — single file, +23/−1.

Tests run

  • Comparison base: main @ 1072200. Candidate: this branch (1 commit).
  • Markdown structure verified: "Viewport height budget" nests under "Executable geometry rules" alongside "Spacing and labels" / "Repair order"; no heading regressions.
  • No automated checks apply to prose; archify doctor unaffected (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.md content.

@coderabbitai

coderabbitai Bot commented Sep 8, 2026

Copy link
Copy Markdown

Review Change StackReview Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Advanced

Run ID: de7ffccc-808a-4886-8ef8-4eb2da4f4000

📥 Commits

Reviewing files that changed from the base of the PR and between 1072200 and bf7995c.

📒 Files selected for processing (1)
  • archify/references/authoring-contract.md

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.


📝 Summary

Summary

  • Expanded the authoring contract with a quantitative viewport-height budget for the 1440×900 first screen.
  • Documented that absolute rendered height, not viewBox aspect ratio alone, determines overflow.
  • Added concrete via[0] coordinate constraints for the via direction contract.
  • Added guidance for estimating overflow and repairing geometry when visual-check reports overflow.

Compatibility impact

  • Documentation-only change.
  • No code, schema, defaults, acceptance rules, generated artifacts, or existing behavior changed.

Validation

  • Author-reported: Markdown structure was verified. No automated tests apply.
  • Observed at the current head: not yet available.

Walkthrough

Changes

Authoring contract

Layer / File(s) Summary
Geometry and viewport guidance
archify/references/authoring-contract.md
The contract defines via and fromSide segment orientation, side-midpoint anchoring, viewport-height estimation, recommended first-screen dimensions, and overflow repair steps.

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 bf799

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)

Check name Status Explanation Resolution
Contribution Scope ⚠️ Warning 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 up… Regenerate archify.zip from the candidate source with the canonical Node 22 toolchain using scripts/build-zip.sh, commit the updated archive, and update the Generated artifacts section with the regenerated file and freshness evidence.
Validation Evidence ⚠️ Warning The changed file is a packaged Skill instruction, not repository-only prose. CONTRIBUTING.md requires npm test for packaged Skill/authoring changes and requires ZIP freshness for published Skill-ins… Run npm ci && npm test in archify/, rebuild the canonical archive with Node 22 using scripts/build-zip.sh, commit the refreshed archify.zip, and update the PR template with the exact command results. Explain the regenerated artifact…
Full details: Contribution Scope

Explanation

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 archify/references/authoring-contract.md; archify.zip is unchanged and its archify/references/authoring-contract.md entry matches the base, not the candidate. CONTRIBUTING.md requires ZIP freshness checks for published Skill-instruction changes, and the PR's claim that no generated files reference the content is therefore incorrect.

Full details: Validation Evidence

Explanation

The changed file is a packaged Skill instruction, not repository-only prose. CONTRIBUTING.md requires npm test for packaged Skill/authoring changes and requires ZIP freshness for published Skill-instruction changes. The PR reports that no automated checks apply and does not provide those results. More importantly, the tracked archify.zip was not changed, and its archify/references/authoring-contract.md entry still contains the pre-change text; a direct source/archive comparison reports archive_matches_source=false and the first difference at the new direction-contract bullet. CI explicitly rebuilds the ZIP and fails when it differs, so installed users would not receive this change.

Resolution

Run npm ci && npm test in archify/, rebuild the canonical archive with Node 22 using scripts/build-zip.sh, commit the refreshed archify.zip, and update the PR template with the exact command results. Explain the regenerated artifact and keep the non-visual visual-evidence entry as Not applicable with its reason.


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.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant