Repository navigation
Global Styles: List elements alongside blocks - #81645
MaggieCabrera wants to merge 27 commits into
Conversation
|
Size Change: +2.3 kB (+0.03%) Total Size: 7.73 MB 📦 View Changed
|
|
Flaky tests detected in 10e10af. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/31822047274 adds and activates a new tab when pressing Enter at the end of a tab label in
|
MaggieCabrera
changed the title
|
/cc @jasmussen @fcoveram @yjailin @elizaan36 I'd love your feedback on this |
|
Nice, this is a great start to iterate upon: 
I look forward to feedback shared by others, and if she'll permit me one more ping today, I'd love input also from @beafialho. One thing: We should consider whether this should have a special group like "Blocks", with descriptive text, or whether it could just be a menu item in the list of other items (Colours, Typography), etc. And also whether "Form elements" needs to be a sub-group within elements, or the form controls can just be shown directly in the list. I've no strong opinion here. |
|
I'm not sure about this idea. I understand the logic, but the concept “Elements” is not as handy as blocks. Editing a “text” element feels detached from the component that renders it: block. I acknowledge that style categories like Typography and Colors already mix elements that belong to blocks, like heading, but these categories are more common in other products and the mental model feels more natural. The path Element > Text does not much. Since elements are currently placed inside the block settings, I would keep them there for now. Maybe the exploration is on revisiting the list of blocks so the UI-related ones (Form, Input, Select, etc) are reached out differently. At the end, everything inserted in the canvas is a block. |
|
I had to learn a bit what Elements were since, as I had played with it so far, it seemed to only change colors and nothing else. We should consider choosing a different term or clarifying the nomenclature—it's not clear for users that aren't familiar with HTML. I now understand the relevance of it being in Global Styles, even though at first it seemed a bit redundant being separate from the Typography or Color panels since it seemed to do essentially the same thing. Since these will essentially all move to Elements, we could provide some insight to users through some kind of callout saying "You can now customize the appearance of text, buttons, links, and form controls for the whole site under Elements" or "The customisation for text and colors has moved to Elements". I want to highlight the usefulness of Citation being editable! This has been one of those things I always want to customise in a theme and had to do it with extra CSS. Although let me share when I tested this PR, some of the controls for the citation under Pullquote don't change at all (like Size, Appearance and Color), as I'd expect. Also, for Link, the Decoration panel isn't doing anything at least on my end. I'd expect this to apply an underline to every link on the website, or remove it. It'd be great to be able to customise the |
|
A couple of thoughts after discussing this. Because this excellent proof of concept also surfaces a different issue: "Typography" and "Color" no longer have elements sections, because they would be redundant. So those sections are now just presets: registerd fonts, or colour palettes for your theme. That my be fine, but people might be used to setting heading colours inside "Color", and the font inside "Typography". Now they'd have to go to "Elements". Here's the key part: you can already style elements using those two sections. But not all elements that theme.json supports, and you can only style colour and typography, not background and border/shadow. This is the motivation for the work here: to expand the range of elements you can edit (to also include form controls), and to expand the range of visuals you can change. Add in that the term "Elements" has been confusing, and we might be looking at a good idea that reveals are more underlying IA problem. Two paths forward come to mind. 1. Extend the duplicated elements lists already present 
Today, if you drill into Typography, you'll see a list of elements: 
Drill into each of those, and you can see the Typography panel for each of those elements. Colour has a similar list that drills into the colour panel. In this solution, instead of adding a new bespoke "Elements" drilldown, instead we extend both of those lists to include a broader range of elements (inc. textarea, input, and so on). We do the same for Background, and we rename the current "Shadow" section to "Border & Shadow" (like its panel namesake), and add a list of elements to that screen too. Potentially we can even go a step further, and instead of drilling into only the individual panel for each of those, we can show all the panels across. Yes, each of the four panel-namesake-Global-style sections would list all supported elements in an ItemGroup, each row would link to a drilldown with all available panels for each. Duplicative, perhaps, but also, perhaps, intuitive and simple. 2. Show elements directly in the Blocks list, rename it, and remove the Elements itemgroups from each of the main sections 
That's the direction this PR is going, but taking it a few steps further. We rename it "Blocks & Elements" and moves the item up into the main list. Do we need to differentiate between Cover and Textarea? Maybe we can have subheadings in the list itself, but theoretically we could just merge them. In this direction we'd also remove the duplicative "Elements" sections from each of the major sections (Colour, Typography, etc.) like this PR does, so you'd have to go into Blocks & Elements to style things like headings and captions. I don't totally love either of these proposals, but I'm sharing in case it inspires better ideas. Any instincts? |
💯 Option 2 could make sense to explore further, my only comment is that it still lacks an explanation of what Elements are, but perhaps there is a better placement for that. |
|
I like option 2, can edit this PR to go in that direction. For reference, part of the importance of being able to style form elements (and all elements in general) globally is for plugins and 3rd party blocks that use them to be able to benefit from the theme's styles and look more consistent throughout the site. This is also why I think they need a place somewhere in the UI. I think both options are ok and maybe the name we have used in the code for them doesn't need to be the same as in the UI. |
The problem with Option 1 is we are still missing controls like spacing. We have layout, but that is a different concept altogether. It's also ok I guess to not do everything in one go. Typography and colors is already a good chunk of what GS for these type of elements are going to need. This is a complicated subject because Elements are something we built to fill in gaps that blocks couldn't yet. Another alternative to this PR is to keep progressing and land the form block and use that as a way to style these elements as their own block just like button does. But the problem with that is that 1: it's a much more complicated and long solution and 2: we are already half way there with elements having theme.json support and themes already out there making use of it. It's still something that can happen on top of elements having their own place in the UI, so I wouldn't make it the only condition to have a UI for elements. |
To me this is the main friction point where I'm hesitating about the solution. Not because making certain elements more affordable doesn't add value, but because the term "Elements" is not clear. One of the benefits of the current UI is that blocks in Global Styles are coherent with how those work in the Canvas. That connection makes it possible to show the global style panel while editing a document. If Citation lives in “Elements”, then we start to derail that connection as there is no way of adding a “citation element" in the Editor. In that vein…
…this sounds like a style that should be controlled via a block inside Quote block, or a section in the style tab of Quote block. Something like how Playlist styles the waveform. 
With the above in mind, I see potential in option 2. Although…
I'm not sure about this. That repetition adds value because it’s a shortcut for controlling elements directly related to the section. Styling headings and a paragraph in typography makes sense, but it also makes sense to go to: Blocks and Elements > Paragraph. Mixing blocks and elements in a single drilldown could be a good idea. There is no need to explain what elements are; instead, we can create categories that group related ones. Something explored by @keoshi here in #44840 A category named Form could list elements such as Select, Input, and others. What do you all think of this? |
|
@jasmussen on your first question, I'd make it a group with a heading rather than a menu item, and I think the reason also answers the naming worry. Right now a section can hold two different kinds of thing. Typography holds font presets and a list of elements. Color holds the palette and a list of elements. That's what makes it unclear where to go, more than the word Elements does. So I gave each part of the panel one job. The top list defines what the site has: Typography, Color, Background, Shadows, Layout. Elements is where you style things: Texts, Buttons, Form controls. Blocks keeps its existing description below. 
Text opens into Headings, Text, Links and Captions, since those genuinely differ. 
Form controls opens straight into settings, because the point there is that inputs and selects match. One row each in Elements, different contents. 
I also shortened the preview card so more of the list is visible, and added dividers between the groups. On the cascade: Elements sets the baseline, and a block placed on a page can override it. That's already how per-instance styling works. What it leaves open is the layer in between, the per-block entries in Blocks. My instinct is a block should only keep its own entry when it adds something the element doesn't have, and the rest should defer. That's also what would stop the same thing appearing twice with no rule for which wins. On Typography and Color becoming presets only: I think that's fine, and better than the current split, because it's one rule to learn rather than remembering which section holds which element. @fcoveram on losing the shortcut in Typography and Color: I think it's worth it. One place to go beats two that each do half the job. And as Maggie said, we can pick a clearer label later without changing the structure. |
|
Thank you for the visuals. You outline a decent third path forward. I'm curious what other folks feel about this. |
|
@yjailin form elements is not just inputs and selects anymore. We have labels now too. I think we should still list them and drill down |
|
Another question. I have been reading up on the development in the Form block (currently an experiment) and even though it seems block/temporarily abandoned, I want to assume that it will one day land, and we will have to deal with the issue of having the input/label element and the input/label blocks in Global Styles. How does that affect our decisions for elements today? |
|
@jasmussen sorry i don't mean to add noise, but I just came out with this other version. I think there would be a confusion between Typography and Text... If the distinction between styles and elements is too complex, we can just keep Typography as it is, And drop the group labels for one clean list with two lines: "your whole site" vs "a specific block." Reads clearer to me, wdyt? 
@MaggieCabrera agreed labels should be stylable. But I'd question separate drill-downs for inputs and selects, styling them differently doesn't really add value, and a form where they don't match looks worse. My instinct is one shared screen for all form controls, labels included. One quick check: when you say "labels," is that just the field label (Email, Name) or the text shown inside the control itself? Want to be sure we're talking about the same thing before deciding on drill-downs. One more thing on colors: there's a Colors section on the main screen (Inputs, Selects), but each Typography drill-down also has its own Color. Feels like color lives in two places. Is that intentional, or should color sit in just one spot? I am not a site editor specialist, just asking with fresh eyes. |
|
This is a great discussion, it's very productive and useful, thanks to all who participate and contribute, genuine kudos. I'm also starting to get the sense that it might be good to break this effort into two steps: 1 step that is as simple as possible that we can let Maggie merge so we can start to get a sense of things, and the other step where we further the categorisation of things based on what we might learn. Essentially a clouds (vision) and mud (stepping stone to the vision) approach. That's not to dismiss any of the good feedback, I like your latest Yoann (except perhaps I'd still put "Buttons" under form controls rather than keep it separate). But mostly to try and bias us all towards some action that can hopefully boost overall confidence in the vision that is forming. For me, the most tangible improvement that this PR makes, is surface elements in global styles that weren't previously there. This is a material improvement that feels worth doing on its own, regardless of any categorisation improvements we can do separately. Bea already notes it: the ability just to style the citation is a big win on its own. Is there a way we can break this effort into the two?
This comment breaks it into two paths forward: keeping "Elements" subgroups under each major category, vs. consolidating them in a new section. Pros and cons to both. But if our goal is to ship the smallest footprint first iteration so we can boost our confidence on what to do in a followup, which of these would be the best first step to take? Curious what you think @MaggieCabrera: keep Elements itemgroups, or create a new section as this PR does.
Good question. One rule of thumb I've always worked from is: if you can style it in theme.json, there should (with few exceptions) be a UI for it in global styles. So if that form collection block lands, we will have to support both as styleable. For me this actually says we should have a section called "HTML elements" (or ideally a better but still clear term), rather than mix terminology too much. Keep blocks and elements distinctly separate: we probably want to avoid a single form controls section that mixes both blocks from the Forms block, with its native HTML counterparts. We might also want to consider two levels of drilldown in the "Blocks" section, where child blocks (e.g. Form > Input) lives as a child of its parent. |
|
Another thought: good block themes style all blocks and elements for you, so you don't have to. When you enter global styles, while you should be able to restyle everything, probably you'll be wanting to make big sweeping changes, like editing palettes or font presets, rather than atomically restyle each block. That may let us keep "Blocks" and "Elements" slightly separate in the main list, something to dig for. |
Conceptually they might be but not technically. I don't think we have a single instance of one set of controls that serves CSS for two different elements/blocks. Plus the select component brings some complexities of is own that should be dealt separately (like the arrow and the dropdown). |
|
I think the best option for this PR to move on would be option 2, for the main reason that it lets us include all kinds of controls (border, shadow, spacing...) for every element without needing to add extra items to the initial list. We can rearrange and revisit as we see fit. |
|
@MaggieCabrera @jasmussen Happy to design to the constraint so we can ship. I'll follow up with you in Figma. One flag for the follow-up: per-element splitting is hard to scale, with this many control types it's 40+ typography drill-downs, and most users want their controls to match, not diverge. So for step two I'd love us to aim for one shared "form controls" surface, even if it's many elements underneath. |
I don't thing we are ever going to be doing 40+ elements? |
|
Quick clarification, I think we've been counting different things: I mean control types, not HTML elements. With option 2, each control type gets its own drilldown, and that's what adds up. I don't want to hold up step one over it though. My ask is really for step two: i think consolidation would be better for the user's side, not the markup's. Here's a Figma showing both: 
Same entry through Elements, then two directions. Consolidated: one Form controls surface. Per-element: every control type as its own row. Same styling power, very different to navigate. |
I'd agree with @yjailin here that we should aim to simplify the control surface as much as possible. There's the potential with elements to go in exactly the opposite direction with many more different places to style the same elements and I'd avoid creating even more complexity for users in the site editor. Backing up a little bit to think through the user problem to solve. Checkout, account, and theme forms have historically picked up mismatched styles or required theme-specific patches. @yjailin has designed a shared model using WordPress Design System components, documented its states, and built a working prototype where all of these fragmented controls can live at a unified higher level. This is what he's shared in this comment and elsewhere on P2 and in Design Review. Since we already have the concept of “Elements” built in Global Styles for reusable controls such as buttons, text, and form inputs, we agreed it's a good idea to have the immediate goal of a small shippable step, as long as it's followed by clearer grouping as the model is tested. If we went with option 2, this doesn't feel like the small shippable step moving towards the end goal. If we went that direction, the form controls should also be placed at the higher level as well so that we don't go back to the same issue of mismatched styles and fragmented experiences. This is super relevant for Woo because Purple, Mercantile, and other block themes should inherit one styling model instead of solving checkout inputs and other controls theme by theme. Thoughts? |
|
I really don't see this going towards one "form element" that carries all the controls that will be used by everything. I understand where you are coming from but essentially, styling inputText today in theme.json is already stling textarea, input:where([type=email],[type=number],[type=password],[type=search],[type=text],[type=tel],[type=url]) all in one go. We are not aiming to match CSS in the UI, so Core will never surface a "email/number/url/password input form" element, it will all be covered by input text (as it is today, remember we are only building a UI for a framework that is already set in place). |
Blocks and elements are listed together under one item in the main Styles menu, so there is a single place to style anything on the site. Inputs, selects and buttons are grouped under Form controls. Elements now offer the background, spacing, border, shadow and custom CSS controls that theme.json already accepts and the styles engine already emits, instead of typography and colour alone. Sizing, block gap, text alignment and duotone stay out: the first three belong to the block that contains an element, and the engine emits nothing for the last two. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
An element was previewed as a letter specimen built from a handful of properties copied across by hand, so it could not react to the border, shadow, spacing or background controls elements now have. Each element is previewed instead as a sample of the markup its selector applies to, rendered in the editor iframe with the generated stylesheet. The sample picks up the cascade, the theme's fonts and every panel without a list of properties to keep in sync. Text color and background color are left to the Typography and Background panels, where they were relocated in #77279, rather than shown a second time in a Colors panel. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Elements sit in the same list as blocks under Elements, Headings and Form controls subheadings, with no drilldowns between them, so everything that can be styled is one screen away and easy to find alongside blocks. Each heading level is its own row, and the button element is labelled to tell it apart from the Button block further down the list. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The typography panel had its own wrapper that read the element's styles and settings a second time, separately from the panels beside it. One component now resolves them and renders every panel. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The block and element screens each carried their own copy of the border reconciliation and of the check for whether custom CSS may be edited. Both now use one shared version. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Bring back the root Text screen under Typography, which the style variations tests depend on, and list "All headings" at the top of the Headings group so the shared `elements.heading` node themes style can still be edited. Update the unit expectations for the widened element supports, the e2e labels for the renamed "Blocks & Elements" screen, and add the PR links the changelog check requires. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The rebase left the entry under the published 17.0.0 section, which fails the changelog checks. Also restore the formatting of an older entry the branch had touched without reason. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Text alignment was added to elements in #73854, and the element screens should keep offering it alongside the new panels. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Moving the element colors out of the Colors screen dropped the only control for link hover color. The link and button element screens now offer the states the package already defines for them, and follow the setting that turns off state editing for blocks. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
An element's background image with no size renders with cover, as a block's does, so the element screens now show the same defaults as the block screen. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The block list's elements now open through a single path with the element name as a parameter, instead of one route per element. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The Blocks & Elements list now reads each element's label from the element screen's table, so the two cannot drift apart. The Button element's screen is titled "Button (element)" to match its row and tell it apart from the Button block. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The preview's own class now sets its side margin, and no longer shrinks inside the screen's scrolling flex column. This removes the element screen's use-recommended-components suppression. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Restore trunk's Typography element list with only the Text row, instead of rebuilding it inline. The row keeps its sample in the site's font, and the other elements stay in the Blocks & Elements list. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Trunk published new releases, so the rebase left the entries under published versions. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Trunk removed the dot from block rows in #84657. Element rows follow, and the customized filter keeps working for both. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
c931c87 to
1680f55
Compare
Trunk's fallback helpers stay where they were, and the border handling the element screen shares becomes an exported function next to them, instead of a new file. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The element list calls the existing value check directly instead of a separate exported wrapper. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Element screens moved under the Blocks & Elements path, so the Style Book showed every block for them instead of the Text category it showed when they lived under Typography. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Searching "h1" now finds Heading 1, and "form" lists the form controls. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
MaggieCabrera
changed the title
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
mikachan
left a comment
mikachan
left a comment
There was a problem hiding this comment.
Thanks for pushing this through, @MaggieCabrera, and everyone for the thorough design discussion. I went through the code and the latest comments. The layout matches the direction @jasmussen proposed (one flat list with subheadings, singular names, All headings first), and the rest is looking good: a single /blocks/elements/:element route, block-link.js skipping it, the Style Book showing the Text category, and the shared border and CSS-capability helpers. Element colors also aren't lost from the old Colors screen, since text color is now in Typography and background color in Background.
One thing I think we should change before merging is the formInput icon. This PR adds it to @wordpress/icons, with a manifest entry and changelog entry, while #84074 is a draft at the moment and it seems that we're still discussing whether elements need icons or not. If this merges first, the icon will be public. Could we use an inline SVG local to global-styles-ui for now, or leave element rows without icons?
| ### Breaking Changes | ||
|
|
||
| - Rename Tabs-related icons: `tabs-menu` to `tab-list`, `tabs-menu-item` to `tab`, and `tab` to `tab-panel`. ([#77418](https://github.com/WordPress/gutenberg/pull/77418)) | ||
| - Rename Tabs-related icons: `tabs-menu` to `tab-list`, `tabs-menu-item` to `tab`, and `tab` to `tab-panel`. ([#77418](https://github.com/WordPress/gutenberg/pull/77418)) |
There was a problem hiding this comment.
This change seems unrelated, we should probably revert it.
| * is left out entirely (aspect ratio, height, width and their minimums) | ||
| * because an element is sized by the block that contains it. | ||
| */ | ||
| const ELEMENT_BLOCK_SUPPORTS: string[] = [ |
There was a problem hiding this comment.
Since ELEMENT_BLOCK_SUPPORTS starts from ROOT_BLOCK_SUPPORTS, elements keep contentSize and wideSize. The width controls never render because ScreenElement doesn't pass includeLayoutControls, but useHasDimensionsPanel still counts them. So on a theme that sets layout widths without enabling padding or margin (no appearanceTools), every element screen shows an empty "Dimensions" panel. Filtering contentSize and wideSize here alongside blockGap would fix it. The expected lists in test/private-selectors.js would need updating too.
This branch has not been deployed
10 participants
What?
Closes #81649. See #34198, follow-up to #80852.
Styles > Blocks & Elements now lists elements next to blocks, under Elements, Headings and Form controls. Every element gets the background, dimensions, border, shadow and custom CSS controls
theme.jsonalready accepts, and links and buttons get their states, like hover.Why?
Themes can already style inputs, selects, buttons and citations in
theme.json, but most of that had no UI, and what did was split between Typography and Colors. Now it's all one list away, including the form controls that plugins and third-party blocks inherit.How?
theme.jsonor schema changes.Testing Instructions
Testing Instructions for Keyboard
Repeat the steps with Tab and Shift+Tab to move between controls, and Enter or Space to activate them.
Screenshots
Use of AI Tools
Codex and Claude Code helped with research, implementation and tests. I reviewed the code and the behavior.
🤖 Generated with Claude Code