This was the style for News, but I don't think it's expected here. Remove the background on hover, keep the animation and underline.

When viewing https://wordpress.org/documentation/ on mobile,the subnav menu is misaligned.

Screenshot

How to test

1. Visit https://wordpress.org/documentation on a mobile device
2. Expand the subnav
3. Notice the menu overlaps oddly.

To fix an accessibility issue in the About 6.3 page, the video element in a custom html block needs inline style display: block. This style is being stripped on save though, so this utility class is being added to work around that.

The child theme here was only added for testing purposes. Real use cases will have their own project repos, so this child theme will never be used.

Pages that use a secondary / local navigation (like the Beta/Nightly page for example) don't highlight the selected item.

Here's a proposed change:

• We use the underline to highlight hovered elements
• We use bold to highlight the current page

Currently, the theme provides a "monospace" font, but it's just using the default monospace font. It should be updated to IBM Plex Mono.

IBM Plex Mono will be added to the global fonts by WordPress/wporg-mu-plugins#290.

Used for the top border of the updated local header in Learn sites:

This should also fix the missing hover states on the "Outline on dark" style.

Current default states for the buttons:

The design:

See WordPress/wporg-main-2022#30 — Arrows in the content are converted to emoji, but it looks better if they're not, since Inter includes matching arrows. This was done for wporg-main-2022, but other child themes will use similar patterns and should also not have emoji arrows.

For example, in the documentation design:

https://github.com/WordPress/wporg-main-2022/blob/4f8a3a9c1e1f6cb2a3aff648457a85278679d6cb/source/wp-content/themes/wporg-main-2022/functions.php#L88-L100

The site editor currently doesn't load the CSS, which controls the layout of the page. The basic styles are there from the theme.json, but it's hard to build out a page without the correct alignments.

Frontend:

Site editor:

Alternately, switching to a block style for the layout might help load the required CSS, without needing to load the full style.css.

When using the alignment left of right on an image it doesn't show on the front end.
The example is a the WebAssembly logo in the public preview draft

Editor:

On the front-end it is also left aligned but the next paragraph doesn't wrap around it.

This pattern is like the "Latest release" section on News. A big heading, with an arrow, in a container with a background color.

Mockup:

The container group might also have other content (or maybe this is unrelated content just below it?)

That doesn't look right, and won't fly. I don't think we necessarily need a hover style in this case (on this background) and the focus style can be white, a la what's on news

See WordPress/wporg-developer#164 (comment)

The line height for the pagination control is tight on mobile. We should fix this layout with a line-height change but also consider a solution for the dots.

Screenshot

Headings are EB Garamond, and body text is Inter. These are set in the theme.json. In a few cases, elements in the mockup use the opposite font though, so we need to be able to control that somehow.

This should be a p, but it's using the heading font.

Maybe block styles? Or is there a block-level font family control we can use?

The Link and Arrow style used on the w.org homepage, showcase and enterprise pages (and maybe others) doesn't support RTL reading direction:

Home

Enterprise

Showcase

Steps to repro

1. Open any of these pages
2. Add attribute dir="rtl" to the HTML element
3. Scroll to the bottom of the page and observe that the arrow is pointing the wrong way, and when hovering it also moves in the wrong direction

The redesigned About/Features page has list items with long format content which require more spacing than normal:

It has been suggested that we should add a new block style, as the list block doesn't use block gap for this.

See WordPress/wporg-mu-plugins#175

If we want to use this project in separate child-theme repos, it needs to have a branch with the built CSS files.

As part of the other improvements for the local navigation (highlighted style, and item alignment), we'd like to add two small changes:

• Reduce the font size of the local nav items so they are similar to those of the global one (14px)
• Reduce the margin between the items (from 30px to 24px)

We could use something between the 0 spacing size and the Custom (0.5rem) size for spacing in the Row block for post meta so that By Date in Categories reads more naturally. Just needs to be a tiny bit narrower.

Another option might be enabling custom spacing sizes in the theme.json for these situations:

This is made up of a Row block that wraps Paragraph + Post Date + Paragraph + Categories.

I tried adding before/after spaces in the Paragraph blocks themselves, but the editor trims them.

Question: What's the difference between an Archive template and a Category template

?

Wouldn't Category template be redundant?

See WordPress/wporg-showcase-2022#62, WordPress/wporg-mu-plugins#302, and WordPress/wporg-mu-plugins@2ca5e5b. The spacing to the left and right of content in the header & footer was updated to be 80px on large screens, and snap down to 20px on small-medium screens (<890). This left the page content out of alignment, because the parent theme sets this value on a scale.

A new spacing preset called "Edge Spacing" has been added to the parent theme (df307d7). We'll use this value (or --wp--preset--spacing--edge-space if CSS is needed).

• Developer Blog
• Documentation — remove --wp--preset--spacing--60 workaround
• Main WordPress/wporg-main-2022#158
• Showcase

Previous notes

In the wporg-documentation-2022 theme, I've added a local override to get these to match up. We should fix this in the other themes too. We can use a temporary local workaround so the change doesn't break other live themes. Once this has been fixed in the other themes, we can update the large spacing value in the parent theme, and remove the local workarounds.

Foundational	Secondary

Desktop	Mobile

Update wideSize to 1160px.

Look into spacing presets

The default table style uses a font size which is too small:

• Bump the font size of jazzers inside the WordPress history release table. It should be at least the same font size as the body text above.
• If we use tables like this, with a smaller font size inside, elsewhere on the site, we should bump those as well.

History page

Roadmap page

Initially reported here: https://meta.trac.wordpress.org/ticket/6447

When this pattern is used, only the text is clickable despite the arrow appearing to be part of the link.

Maybe we should assume that a heading using this pattern will always have a link, and add the arrow on a.

Ref: #19 (comment)

There's something awkward happening at mid-sized screens (600 - 1080) for the pattern: heading-with-arrow

One of the things we've explored as part of the refreshed Showcase, is a more systematic approach to a spacing grid. Instead of a variety of different variables (15, 16, 20, 44), have a neater grid system (10, 20, 30, 40) etc. We are already applying this, in a static form, across website refreshes and notably the Showcase refresh.

There may be a challenge in rolling this out, in part even if a grid system wasn't fully evolved in the Figma mockups until recently, there was one for the WP.org parent theme: https://github.com/WordPress/wporg-parent-2021/#spacing

Secondly, because rolling out new values here may end up causing some issues in other designs that leverage the existing system, such as News. A fair bit of the way, the new grid system sticks to the existing base10 increments, but the web-spacing system includes some clamp based values:

The Figma-based grid system and web-based grid system don't have to match, Figma will show static mockups, after all, whereas on the web values will need to be responsively smart to as to scale with the viewport.

But perhaps there is an opportunity to still sync up part. This codepen outlines an idea of essentialy splitting out the clamp values from the grid values, and leveraging the latter to power the former. To distill it with an example:

	// Base grid, matches Figma
	--s-04: 4px;
	--s-08: 8px;
	--s-10: 10px;
	--s-20: 20px;
	--s-30: 30px;
	--s-40: 40px;
	--s-50: 50px;
	--s-60: 60px;
	--s-70: 70px;
	--s-80: 80px;

	// Responsive spacings, web
	--3x-small: var(--s-10);
	--2x-small: var(--s-20);
	--x-small: var(--s-30);
	--medium: clamp( var(--s-40), calc(100vw / 16), var(--s-60) );
	--large: clamp( var(--s-20), calc(100vw / 18), var(--s-80) );
	--x-large: var(--s-100);
	--2x-large: clamp( var(--s-80), calc(100vw / 7), var(--s-120) );
	--3x-large: clamp( var(--s-80), calc(100vw / 7), var(--s-160) );
	--edge-space: var();

☝️ The above is just a sketch, the actual implementation and variable names I'll defer to those implementing it. But the core idea is that the base grid matches Figma, figma can use those for static non-scaling mockups, and then the web can build clamp-based responsive values based off of them. The benefit would, theoretically, be a closer link between mockups and final result.

Would this be useful?

Required for the Developer home page, and subsequent redesigns.

Should support 2 and 3 column configuration. 3 columns should change to 2 on medium screens, and both to one on small screens.

This initial style will be added to list blocks. The expected markup is:

<ul>
    <li>
        <a>
            <strong>{title}</strong></br>{detail}
       </a>
    </li>
</ul>

States:

Developer Design:

See: WordPress/wporg-showcase-2022#25 for more information.

Currently the grid expects children to have markup like:

<!-- wp:heading {"level":3,"fontSize":"small","fontFamily":"inter"} -->
<h3 class="wp-block-heading has-inter-font-family has-small-font-size">
    <a href="https://developer.wordpress.org/apis">
        <strong><?php esc_html_e( 'Common APIs', 'wporg' ); ?></strong><?php esc_html_e( 'Interested in interacting with various APIs?', 'wporg' ); ?>
    </a>
</h3>
<!-- /wp:heading -->

However this isn't ideal because the output text has the 'title' and 'description' jammed together for anything that disregards the strong tag. A better html structure is to wrap separate elements in an anchor tag. We have a block in mu-plugins which does exactly this, the LinkWrapper:

<!-- wp:wporg/link-wrapper -->
<a class="wp-block-wporg-link-wrapper" href="https://make.wordpress.org/cli/">
    <!-- wp:heading {"level":3,"style":{"typography":{"fontStyle":"normal","fontWeight":"700"}},"fontSize":"small","fontFamily":"inter"} -->
    <h3 class="wp-block-heading has-inter-font-family has-small-font-size" id="cli-handbook" style="font-style:normal;font-weight:700"><?php esc_html_e( 'CLI Handbook', 'wporg' ); ?></h3>
    <!-- /wp:heading -->

    <!-- wp:paragraph {"fontSize":"small"} -->
    <p class="has-small-font-size"><?php esc_html_e( 'A collection of helpful guides and resources for using WP-CLI.', 'wporg' ); ?></p>
    <!-- /wp:paragraph -->
</a>
<!-- /wp:wporg/link-wrapper -->

We need to update the styles to expect this markup instead.

The style should remain the same, eg.

The new themes are designed to work with the Gutenberg plugin installed, so we can make use of new features and fixes.

This means that if the plugin is disabled, and the site reverts to core's bundled editor, some features or layout might change.

To avoid this, the parent theme(?) should either prevent the Gutenberg plugin from being disabled, or at least alert if it gets disabled. It could produce a dashboard notice and/or ping the dotorg-alerts channel.

Context: https://wordpress.slack.com/archives/C02S78ZAL/p1662983457375559

This regression happened because the plugin was inadvertently disabled.

This is likely going to be a technically difficult challenge, and it isn't one that I would consider a priority. Filing here so it's captured: let me know if this isn't the right repository for this!

The News page has a lovely new 404 page: https://wordpress.org/news/404:

Every other section on the site has its own spin on 404 pages, including:

• https://wordpress.org/themes/404/
• https://wordpress.org/learn/404/
• https://wordpress.org/404/

While the main header section is likely going to change between these, the content and footer should probably be unified across all of these, so we have a single consistent 404 page design.

The parent theme inherited a lot of look & feel from News, but most sites we build will it will probably be more like wporg-main-2022 (full pages) rather than a News blog.

If we look at wporg-main-2022 and the other sites we might use this parent theme for in the future (ex, showcase, various directories, 5ftf, etc), they don't have blogs. The only templates we would need to provide are an index.html so the theme works, and a blank page.html (like this) so pages can be built up in the editor.

The wporg-developer-blog theme is a child theme, but the majority of templates can be moved into that theme where they're useful.

This way, the parent theme becomes the provider of the design library (by way of theme.json), shared blocks, block styles, and patterns, and we'll use a process like we've settled on in wporg-main-2022 for the other sites.

At the moment, selecting text and items highlights in red/orange/coral, which has an appearance of being a warning:

Additionally, it doesn't invert the links, and is not quite as flexible as the native highlight color. Let's remove the custom highlight for now.

I started some of this in this comment: #18 (comment)

This should be somewhere more central (a readme somewhere).

ideally, the theme would use postcss like wporg-mu-plugins does.

xref WordPress/wporg-mu-plugins#6 (review)

the sooner we do it, the easier it'll be, but i'm also leery of getting bogged down in non-essentials right now 🤔

8270ecd1f04223c53a9ffcc6a81fa118f5ba8a09 added %footer-archive-dark, %local-header-off-white, etc. If PostCSS doesn't have a similar concept, we might be able to convert them to regular classes, and have the templates add the class, but that would rely on WordPress/gutenberg#32939

we currently import some mixins, breakpoints, etc from gutenberg's sass. i'm not sure a good solution for that

there may be a tool that'll convert most sass to postcss automatically

See WordPress/gutenberg#42763 — This new constrained layout type replaces the inherit: true setting in layout, and constrains the inner content to use the given content/wide width (vs no constraint = full screen width).

The new layout setting will be released with GB 14.0, though the old setting will probably be supported still (how long?)

We should update the parent & child templates (wporg-main-2022) to use this new setting.

I think the patterns in wporg-main-2022 would update automatically with the build:patterns script, but worth checking that too.

For example:

- <!-- wp:group {"layout":{"inherit":true}} -->
+ <!-- wp:group {"layout":{"type":"constrained"}} -->

("On Hold" because technically 14.0 is not out yet, but it should be released today)

When I saw the ↗︎ emoji in that link, I assumed it was being used to indicate that the link opens in a new tab or was an external site, because of how similar it is to the the icons that are commonly used for that purpose. It seems to me like the upwards arrow is the substantive part that communicates an "exit" from the site/tab, and the surrounding box is decorative.

@shaunandrews and @jasmussen mentioned that ↗︎ was only meant to be decorative, though. I wonder if we should consider a different emoji for that purpose, to avoid confusion?

When adding code blocks, most code is displayed in a truncated fashion. Maybe we can increase readbility to allow align wide and full width to code blocks?

See: https://meta.trac.wordpress.org/ticket/6999

When selecting text in the subnav, the page scrolls upwards. This is true for for both its use in the wporg-documentation-2022 and wporg-developer themes.

Example URLs

• https://wordpress.org/documentation/category/about-wp/
• https://developer.wordpress.org/redesign-test/block-editor/

Screenshot

Props Marc4.

The adminbar seems useful mainly to contributors, which is likely a very small percentage of visitors. Can we hide the adminbar on virtually every page, unless you're logged in? Perhaps keep it mainly for the Make sites?

I think this should ultimately be a ticket in meta since it's a significant change. Leaving this ticket open here for now.

On the home page in the lower area, where the latest news are displayed, there are errors in the output of HTML within post titles. HTML tags are not removed, but escaped.

I'm working on a new page in w.org, and it looks like I've encountered a bug with the separator block when it uses the dots style

The page uses the Template page-download in case that's related

Link to the draft page

A new dark charcoal and a lighter charcoal have been added to the color system. We can add them with minimal changes by zero-indexing the charcoal set.

The one instance of charcoal-5 in wporg-mu-plugins (#1c2024, for the header hover color) can be renamed to Nero to prevent confusion with this set of main colors.