docs(webkit): add the one-content-column principle to webkit-ui-craft - #859
Merged
Conversation
Building the console rail surfaced a failure mode the skill had no words for: inside a vertical list, every row's content must start on the same x — a section title's text, a row's leading glyph, and a row with no glyph at all. Three concrete bugs follow from breaking it, and each one happened: an empty glyph box that misreports where content starts, an indent derived from a literal so a rail comes unstuck from the rows it connects, and a structure line drawn past the row's box edge so it paints under the hover surface. It also says to verify the column by measuring the rendered x of each row type rather than by looking, because a 4px break is invisible in review and obvious in production.
robsongajunior
approved these changes
Aug 5, 2026
isaque-bock-azion
approved these changes
Aug 5, 2026
robsongajunior
approved these changes
Aug 5, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Building the console rail (#853 / #854) surfaced a failure mode the skill had no words for, so it kept happening.
The principle
One content column. Inside a vertical list — a nav rail, a menu, a settings list, any stack of rows — every row's content starts on the same x, whatever the row is. A section title's text, a row's leading glyph, and a row with no glyph at all all begin on that column. A row that reserves a glyph box pads by the column minus the glyph's own centring, so the glyph lands on it rather than the box. Nesting shifts the whole column by exactly one indent step, so the alignment cascades at every depth instead of being re-derived per level.
Three bugs follow from breaking it — each one actually happened
menu-itemin feat(webkit): add the Menu compound and move MenuItem into it #853.--spacing-*token redefined at a breakpoint — the column would drift as the viewport grows.And: verify it by measuring, not by looking. Read the rendered
xof each row type and assert they are equal; assert a rail's right edge never exceeds the row surface's left edge. A 4px break is invisible in review and obvious in production.Why this is its own PR
git-workflow.mdkeeps shared docs out of code PRs, and this is a shipped skill (packages/webkit/cli-templates/) — it travels to consuming projects, so it is a public interface like a component. It slots in as principle 5 and renumbers the three that follow.check-authoring-docsratchet: 7 known violations, 0 new.