Repository navigation
[Feature]: configurable caption legibility floor / font scale — downstream 9px floor unreachable above 930px viewBox #631
Description
Context
A downstream project (n14) enforces a stricter legibility floor than the upstream 6px (MIN_PROJECTED_NODE_TEXT_PX): caption-class text must project ≥9px at the 930px desktop-reader width (DESKTOP_READER_DIAGRAM_WIDTH). This project-side gate has stood since 2026-09-16 and is currently structurally unreachable for virtually all v3 renderer outputs wider than 930px (a narrow-band exception exists only for pure 11px-label diagrams with no sublabels/context text in 930–1137px).
Arithmetic
- projection:
projected = sourcePx × min(1, 930 / viewBoxWidth) - to hit 9px:
sourcePx ≥ 9 × W / 930→ W=1240 ⇒ 12px; W=1360 ⇒ 13.2px; W=930 ⇒ 9px. - v3 renderer caption sizes (measured on 3.0.1): architecture sublabel preferred 9 / minimum 6 (
renderers/architecture/render-architecture.mjs:42), workflow node label preferred 11 / minimum 9 (renderers/workflow/workflow-compiler.mjs:963), tag 7/6. - ⇒ the projected ceiling is
9~11 × 930/W, i.e. < 9px whenever W > 930 (max 8.25px at W=1240 with 11px labels — this reproduces the ~8.25px figure mentioned in Question: desktop-readability width budget vs preferred text floor — intended headroom at 1440×900? #618).
Field measurement (n14, 2026-09-29)
Scope note: 42 artifacts are delivered; the violation set is 40 current-generation diagrams (plus 1 legacy carried item at 4.65px that predates the current renderer, and 1 passing narrow diagram at 9.0px).
- captionMin projection range 6.0–8.0px across the 40 current-generation violations (full 42-set range 4.65–9.0 includes one legacy carried artifact and one passing narrow diagram); viewBox widths 760–1600px (37 of 42 > 1137px).
- 15 of 41 violations are not width-bound: their smallest caption element is already fitted down to 7–8.8px source by text-fit, so even compressing the whole diagram to W ≤930 still projects only 7.0–8.8px.
- The only current remedies are content removal or ~25% median width compression (p90 ≈ 33%) — both degrade information density for dense-but-legitimate diagrams. A single upstream knob would fix the entire class.
Ask (any of these)
- Configurable caption sizes — expose caption preferred/minimum font sizes (architecture sublabel, workflow node label, tag) or a
fontScalemultiplier, via specmetaor a CLI flag, validated like other authoring options; defaults unchanged. - Reader-width parameter — let authors/downstreams declare the assumed reader width (
--reader-width/ spec field) so the same projection math can be computed against a different budget. - Failing both: document the intended headroom and whether wider-than-930 canvases are considered out of contract (relates to Question: desktop-readability width budget vs preferred text floor — intended headroom at 1440×900? #618).
Why it matters
Any downstream that sets a floor above 6px cannot build wide-but-legitimate diagrams that pass its own gates without deleting content. A knob is a small, local, default-preserving change that unblocks a whole class of compliance work.
Refs: #616 (workflow vertical scroll), #617 (cards rail fixed width), #618 (width budget vs floor).
Activity
ThinkDonk commentedon Sep 30, 2026
Seconding the ask, with the projection math from my side since I think it makes the case cleanly.
I'm generating swimlane workflows from a real ~260k loc C# WMS backend with archify 2.17. My caption-class sublabel renders at 6.6px source, and at the 930px reader budget with a 1000px viewBox it projects to 6.14px, barely over the floor and well under the 9px preferred. The sublabels actually carry content in our case (enum names, class names), so they can't be dropped, and widening the canvas moves the projection the wrong way.
On a 2560px external display the delivered HTML looks completely fine, it's only the 1440 baseline math that squeezes it. A caption font-size or fontScale option with defaults unchanged would unblock my case without asking me to cut information.
tt-a1i commentedon Sep 30, 2026
I'm open to exploring this. Feel free to implement the approach you think gives the best results, whether that involves configurable caption sizes, font scaling, reader-width handling, or changes to the current rules. The existing thresholds and viewport assumptions can be revised too; they are not fixed constraints.
Please pay particular attention to generated diagram quality. Larger text should remain readable without losing content or introducing clipping, overlaps, poor spacing, or regressions in ordinary diagrams. Include before/after examples for dense and ordinary cases, with real-browser verification at representative screen sizes. We should judge the rendered results as well as the automated checks.
If you encounter tradeoffs, we can discuss them during implementation. If the results are clearly better and adequately verified, I'm happy to move toward merging the change. This is closely related to #618, where I've shared the same direction.
ThinkDonk commentedon Sep 30, 2026
Update on my side: just saw #578 and #649 in the timeline. The measured-layout direction in #649 is better than my plain multiplier, so I am parking my own PR and putting what I have (a five-renderer pass, byte-identical default output as regression proof, and the label-literal fold #578 still needs) into those threads instead. The dense-fixture numbers in my earlier comment still stand if they are useful for choosing ranges.