docs(guides): resolve the Send-to fidelity contradiction (preserve substance, adapt form)

[somanshreddy]

Summary

The Send-to guide gave contradictory fidelity guidance: "Keep the original design as a reference" called the rebuild "lossy by nature" (content will be dropped), while the self-review checklist demanded "content match the brief exactly." Neither told Claude Design what to preserve versus adapt, so it genericized distinctive brand content.

Why it matters

On a live Send-to import, CD kept the exact fonts, palette, and hero headline but softened the source design's real figures (2.4M signals/sec, +240% spike) into vague phrases ("streaming now"), losing the specificity that made the design feel live and real. The "lossy rebuild" framing licensed dropping content; the "match exactly" checklist was too absolute to be actionable.

Fix

Resolve the tension around one principle, "preserve substance, adapt form":

• New fidelity rule ("Preserve substance; adapt form"): the form may change (static page becomes timed multi-scene motion; nav/footer chrome dropped or folded in; a hero expanded into a short narrative arc), but the substance must survive verbatim, real headline/copy, exact palette/fonts, distinctive figures/stats/data points, product names, and signature visuals. Do not genericize real specifics or invent numbers.
• Reframed the "lossy by nature" line to mean form adaptation and cross-reference the principle; the original-as-reference still exists to recover anything the rebuild drops.
• Fixed the checklist item so it is consistent (exact colors/fonts + substance preserved verbatim + form adapted) instead of the contradictory "content match exactly."

Documentation only, no structural/contract changes.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
hyperframes	🟢 Ready	View Preview	Jul 17, 2026, 4:41 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[miguel-heygen]

The instruction change is directionally strong: docs/guides/claude-design-send-to-hyperframes.md:89 makes the intended fidelity boundary concrete with real metrics and explicit anti-invention guidance, while lines 386 and 427 remove the old contradiction from the reference section and checklist.

blocker — docs/guides/claude-design-send-to-hyperframes.md:89: this is LLM-facing prompt text, but the PR adds no positive contract test for the new load-bearing instruction. Validate-docs proves syntax, not that a future edit cannot silently restore the exact failure this PR fixes. Add a focused guide-contract test that pins the concepts “Preserve substance; adapt form,” “do NOT genericize,” and “do NOT invent copy or numbers,” plus scoped negatives for the retired phrases “lossy by nature” and “content match the brief exactly.” This is the same prompt-regression discipline used on the related always-delivered import rules.

Verdict: REQUEST CHANGES
Reasoning: The wording resolves the fidelity contradiction, but the behavior remains unprotected against silent prompt regression until the new positive and retired-negative concepts are pinned.

— Magi

[miguel-heygen]

Delta review on exact head ecc2626.

The substantive blocker is resolved: packages/cli/src/commands/claude-design/sendToGuideContract.test.ts pins all three requested positive concepts and scopes the two negatives to the retired contradictory phrases.

blocker — packages/cli/src/commands/claude-design/sendToGuideContract.test.ts:16: required CI is still red. Format fails because the GUIDE readFileSync call is not in oxfmt form; the formatter expands it to a multiline call with a trailing comma. That failure also makes two preflight jobs and preview-regression red, while the required Test job is still pending. Run the repository formatter, push the formatted result, and wait for required CI to pass before this can be approved.

Verdict: COMMENT
Reasoning: The requested semantic contract coverage is correct, but the current exact head cannot be approved while required formatting/preflight checks fail and Test remains pending.

— Magi

[miguel-heygen]

Reviewed exact head b62bed5.

The final delta is the expected oxfmt-only expansion of the guide-contract readFileSync call. The LLM-facing fidelity rule now has focused positive pins for preserve/adapt, anti-genericization, and anti-invention, plus scoped negatives for both retired contradictory phrases. I rechecked the complete two-file diff and prior review history; there are no unresolved threads, the PR is mergeable, and every applicable check is green, including Format, all preflights, Test, CLI smoke, preview parity, regression shards, and Windows.

Verdict: APPROVE
Reasoning: Both prior blockers are resolved on the current head: the semantic contract is pinned and the test is formatter-clean, with all required and applicable CI green.

— Magi