OpenParable
Skip to content
← Back to skills

Debug UI Layout

Design
debug-ui-layout

Debug UI Layout is an Agent Skill for design published in the s4wave/spacewave repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Optimize text copy to fit rendered UI layout using spacewave-debug eval to measure exact line breaks and eliminate orphans.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/s4wave/spacewave/blob/HEAD/.claude/skills/debug-ui-layout/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/debug-ui-layout, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Debug UI Layout Optimization

Use the spacewave-debug eval bridge to iteratively measure how text copy renders at actual viewport widths, then adjust wording to produce clean line breaks without orphans.

Process

1. Identify the section

Find the section by its DOM id or heading text:

go run ./cmd/spacewave-debug/ eval "document.getElementById('section-id')?.querySelector('h2')?.textContent"

2. Measure overall dimensions

Write an eval script to .tmp/eval-{section}.js that collects width, height, line count, and line-height for every text element in the section:

var section = document.getElementById("section-id")
if (!section) return "no section"
var ps = section.querySelectorAll("p")
var res = []
for (var i = 0; i < ps.length; i++) {
  var p = ps[i]
  var rect = p.getBoundingClientRect()
  var style = getComputedStyle(p)
  var lines = Math.round(rect.height / parseFloat(style.lineHeight))
  res.push("p" + i + " w:" + Math.round(rect.width) + " h:" + Math.round(rect.height) + " lines:" + lines + " lh:" + style.lineHeight + " | " + p.textContent.substring(0, 90))
}
return res.join("\n")

Run with:

go run ./cmd/spacewave-debug/ eval --file .tmp/eval-{section}.js

3. Measure exact line breaks

Use the DOM Range API to determine where each line wraps at the rendered width:

var section = document.getElementById("section-id")
if (!section) return "no section"
var cards = section.querySelectorAll("p")
var res = []
for (var idx = 0; idx < cards.length; idx++) {
  var p = cards[idx]
  var text = p.textContent
  var range = document.createRange()
  var node = p.firstChild
  if (!node) continue
  var lines = []
  var lastTop = -1
  var lineStart = 0
  for (var i = 0; i < text.length; i++) {
    range.setStart(node, i)
    range.setEnd(node, i + 1)
    var r = range.getBoundingClientRect()
    if (lastTop !== -1 && r.top > lastTop + 2) {
      lines.push(text.substring(lineStart, i))
      lineStart = i
    }
    lastTop = r.top
  }
  lines.push(text.substring(lineStart))
  res.push("Card " + idx + " (" + lines.length + " lines):")
  for (var j = 0; j < lines.length; j++) {
    res.push("  L" + (j + 1) + ": [" + lines[j] + "]")
  }
}
return res.join("\n")

4. Identify problems

Common layout issues to fix:

  • Orphans: Single word (or very short fragment) on the last line
  • Uneven line counts: Cards in the same grid row should have matching line counts
  • Widows: First line of a paragraph has only 1-2 words
  • Bad breaks: Sentence breaks that split meaning awkwardly (e.g., "full-" / "stack")

5. Edit copy and re-verify

Adjust wording to fix issues. Strategies:

  • Shorten to eliminate an extra line (remove filler words, use shorter synonyms)
  • Lengthen to fill a short last line (add a word or two to push content onto L3)
  • Restructure to shift where breaks fall (reorder clauses, swap em-dash for comma)
  • Synonym swap to change character count at break points ("devices" -> "hardware", "everywhere" -> "across everything")

After each edit:

  1. Run bun fecheck to bump rev and typecheck
  2. Re-run the eval script to verify the new line breaks
  3. Repeat until all elements have clean breaks

6. Quality checklist

  • All cards in the same grid row have equal line counts
  • No single-word orphans on final lines (aim for 2+ words, 10+ chars)
  • Title and subtitle fit on single lines
  • Copy still reads naturally (don't sacrifice meaning for layout)
  • Verify with bun fecheck that types still pass

Tips

  • Card width depends on container queries (@lg, @2xl) and viewport — always measure, never guess
  • At ~226px card width, each line holds ~42-44 characters
  • At ~289px card width, each line holds ~52-55 characters
  • The --file flag avoids shell quoting issues with complex eval scripts
  • Single expressions auto-return; multi-statement scripts need explicit return
  • Keep eval scripts in .tmp/ (gitignored) for reuse during the session