Skip to content

docs(webkit): add the one-content-column principle to webkit-ui-craft - #859

Merged
isaque-bock-azion merged 4 commits into
mainfrom
docs/ui-craft-one-content-column
Aug 5, 2026
Merged

docs(webkit): add the one-content-column principle to webkit-ui-craft#859
isaque-bock-azion merged 4 commits into
mainfrom
docs/ui-craft-one-content-column

Conversation

@gabriel-lisboa-azion

Copy link
Copy Markdown
Collaborator

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

  • Never reserve an empty glyph box. A box with no glyph misreports where the row's content starts: the label sits off the column its siblings hold, and anything drawn from that content (a tree rail, a hover surface) anchors to blank space. This is the exact bug fixed in menu-item in feat(webkit): add the Menu compound and move MenuItem into it #853.
  • Derive the indent from tokens, never a literal. Hold the step and the column in two custom properties and compute the rest, so an elbow or rail cannot come unstuck from the rows it connects. Avoid any --spacing-* token redefined at a breakpoint — the column would drift as the viewport grows.
  • Structure lines live in the gutter, never over a row. A tree rail or elbow stops at the row's box edge, not at its text. The row's hover and selected surfaces fill that box, so a line drawn further is painted underneath them and reads as a glitch on exactly the states a user interacts with.

And: verify it by measuring, not by looking. Read the rendered x of 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.md keeps 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-docs ratchet: 7 known violations, 0 new.

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.
@gabriel-lisboa-azion
gabriel-lisboa-azion marked this pull request as ready for review August 5, 2026 00:58
@gabriel-lisboa-azion
gabriel-lisboa-azion requested a review from a team as a code owner August 5, 2026 00:58
@CLAassistant

CLAassistant commented Aug 5, 2026

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

@isaque-bock-azion
isaque-bock-azion merged commit 94c242d into main Aug 5, 2026
23 checks passed
@isaque-bock-azion
isaque-bock-azion deleted the docs/ui-craft-one-content-column branch August 5, 2026 14:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

4 participants