Gutenberg Integration + Typography Tools (Roadmap)

[ItsJonQ]

I've been waiting for this moment for a long time. After several months of researching, collaborating, building, testing, and iterating, the G2 Components project is nearing a stage where we can confidently map out the initial integration with Gutenberg!

Working with Global Styles and Design Tools had helped me understand many of the complexities and challenges that come from systemizing a UI layer that could accommodate the expansive and open nature of WordPress and the Gutenberg editor. As such, I believe in the importance of introducing G2 Components to Gutenberg in a way that demonstrates user-facing value. I wanted to provide improvements to the UI experience that end-users could see and feel, rather than a revamped architecture that was superficially invisible.

For the past weeks, I've been collaborating with various designers and developers to refine the project. More importantly, I wanted to make sure that it was going in the right direction. (A big thanks to all of these folks for being supportive and patient with my questions). Based on feedback, we felt like a potential candidate to deliver G2 Components with would be to improve the Typography Tools for Full Site Editing (FSE) and Global Styles.

Today, I've created a rough (publicly available) roadmap using Miro. I've found this medium to be easier to visualize a large scale project (at a high level). For finer-grain task tracking, we could use familiar workflows like Github projects. With that said, I'm planning on using this Miro board as the primary task coordination/planning format. As such, items on this board may change over time (e.g. moved around or relabeled).

Link to the Miro board

For this Integration/Typography Tools project, I've split up the work into 4 key phases:

• Prep
• Integration
• Build
• Post Build

Prep

The "Prep" phase contains all of the tasks that prepare G2 for Gutenberg. These tasks involve either cleanup/refactors or resolving critical features (like automatic RTL CSS rendering).

Between the 3 phases, "Prep" is probably the easiest and the shortest. The most crucial part would be to ensure that G2 works correctly with Gutenberg through some initial integration testing.

Initial Integration Testing

All of G2 Component's packages are available publicly on npm. They are updated several times a week, with the latest features and refinements from the project.

To test within Gutenberg, we can add the latest G2 Component packages as dependencies within the Gutenberg repo. Once they're in, we can attempt to use the components in various places in the editor.

All we're doing is making sure the Components and it's systems (e.g. context, styles, substate, etc...) are working as expected within the WordPress/Gutenberg environment.

No pull request will be needed, as we won't be submitting any code into the repository (not yet).

Prep Completion

Once all the tasks are done, and the initial Gutenberg integration tests feel solid, we can move onto the "Integration" phase.

Integration

The "Integration" phase involves migrating all of the packages from the G2 Components repo into the Gutenberg repo. The initial packages would be utils, substate, create-styles, styles, and context (preferably in that order). These systems should not impact the existing Gutenberg code or UI.

These system packages are smaller and self-contained. The migration will help identify and address any issues early (e.g. issues regarding dependencies, build, or types), which will smoothen the move for the components code.

Package Locations

The G2 system packages would live as dedicated packages within Gutenberg, with a slight adjustment to their names.

• @wp-g2/create-styles -> @wordpress/ui-create-styles
• @wp-g2/context -> @wordpress/ui-context
• @wp-g2/styles -> @wordpress/ui-styles
• @wp-g2/substate -> @wordpress/ui-substate
• @wp-g2/utils -> @wordpress/ui-utils

Note: There are other system packages in G2 Components right now. The plan is to drop those in favour of using their underlying dependencies directly:

• @wp-g2/a11y -> reakit
• @wp-g2/animations -> framer-motion
• @wp-g2/gestures -> react-use-gesture

The only G2 package that differs from the above-mentioned migration would be @wp-g2/components.

Component Integration

The idea is to move all of the code from @wp-g2/components directly into @wordpress/components.

The G2 code will mostly be separated into clearly marked directories (most likely __next/).

Below is a rough example of what it may look like:

src/
├── button/
│	├── __next/
│	└── index.js
├── card/
│	├── __next/
│	├── (other files)
│	└── index.js
├── hstack/
│	└── index.js
└── etc...

The G2 code is locally scoped to a singular component directory while encapsulating and signifying that it's the "next"/future version of the component.

In this above example, I've included HStack (one of the new layout-based primitive components). It currently doesn't exist within @wordpress/components. For cases like this, we would use the G2 code directly rather than containing it within a __next directory. Any component that is included in this way should be exported with the __experimental prefix, just like any other new UI introduced to the Gutenberg component ecosystem.

The G2 component code can be split into 3 groups:

• UI that is brand new (don't exist within @wordpress/components)
• UI that can directly replace existing components (current __experimental components)
• UI that to live alongside existing components, but in a "dormant state", activated with the "Context/Adapter" strategy

Context/Adapter Strategy

To ensure integration is done incrementally in a controlled manner, we'll be attempting a strategy that involves G2's Context system and "adapters" for the existing @wordpress/components code.

The Adapter

The "adapter" is a tiny layer that can smoothly translate Component props (API) from the current WordPress components to the new G2 components. This ensures that the systems (core and 3rd party, especially 3rd party) can continue to operate with zero modification required in their UI codebases.

The Context System

The "Context System" works like a "network". It's something that allows components to communicate with each other as well as special "areas" created by the system. By "connecting" our newly adapted components to this network, we can send a signal to specific areas to render the new G2 UI - just like flipping a switch!

First Batch

The first batch of components to hit @wordpress/components would be the ones required to build the new Typography Tools feature. This batch includes the lowest level and most fundamental components for the G2 UI layer (such as View and Text).

Splitting the migration of the components into "batches" will allow us to deliver the new Typography Tools faster.

After the necessary code is moved, and the Typography Tools is built, we can continue with the second "batch" to move the remaining G2 component code.

Integration Completion

At this stage, Gutenberg should not look any different. This is because most of the adapted components are still "dormant". They haven't been signalled to switch to their newer G2 UIs yet. However, all of the foundations, plumbing, and materials have been set for us to construct the new Typography Tools in the "build" phase.

Build

The "build" phase involves constructing the new Typography Tools experience for Global Styles / FSE.

One task we have to accomplish is to streamline the mechanics of how the Block Editor hooks bind and render controls. During the design and development process of the new Typography experience, we established a new unified reset/remove interaction that we feel confident. As such, we'll need to create a systematic way for these interactions to be handled to benefit both the Typography Tools as well as future Design Tools.

Next, we'll designate this new Typography Tools area as "safe for G2 UI" using the Context System.

With those pieces in place, we can start construction on the new Typography tools. (Finally... Finally! We can build something, haha!).

Build Completion

Once the new Typography experience is created, and we're confident it's working correctly with Global Styles and the post editor (with zero regressions caused by G2), we can move onto the final phase, "post-build".

Post Build

The "post build" phase involves us moving the second (and final) patch of components over from G2 to Gutenberg.

That's it!

Next

With the 4 phases completed, the G2 components project would be fully integrated with @wordpress/components and we'll have a new and improved Typography Tools experience.

This is only the beginning! Integration and Typography tools are the first of many steps in systemizing and improving the UI experience for Gutenberg and WordPress. There's still a lot of work ahead of us. From improving the documentation experience to providing a fully-featured Figma Design System experience.

Contributing

I'm 100% open to critical feedback on this outline. If you have any ideas of how we can improve things or spot any gaps that I may be missing, please let me know!

I'm going to start by creating tasks, projects, and milestones for the 4 phases in the respective repositories (first in the current G2 repo followed by Gutenberg). From there, I will be (very) actively coordinating, developing, and reviewing updates.

I recognize that the G2 Component project is inherently complex. It's bespoke and innovative systems are sculpted by the unique requirements of Gutenberg and WordPress. As such, please feel free to reach out to me anytime if you have questions on how things work and how things fit together. For the past weeks, I've been streaming (almost) daily on Twitch. I'm happy to answer questions during the live stream as well!

Thank you all for your time!

[jorgefilipecosta]

Hi @ItsJonQ, thank you for this detailed post.

Regarding dates, What is the planned date to have Build Completion phase ready?

WordPress 5.7 is expected to be released in March 2021 (and the current plan is to include Global Styles in WordPress 5.7), according to what happened in 5.6 the first beta is released two months before which means global styles should be ready and in core in January. When things are in the core they already need to be stabilized tested and be extensible by other WordPress plugins. To allow time to test fix, bugs and make things extensible it seems we would need to have the global styles ready including the g2 typography tools in mid-December.
Is the timeline ok or should we make some changes to the plan?

On the list of components required by typography tools, we are not including wp.components.FontSizePicker and wp.blockEditor.LineHeightControl. I guess these components will also be "migrated" to g2 components?

Currently, the only typography tools part of a WordPress release are Font Size picker and Line Height. So I guess a possible way to go if we are short on time would be to include the __next versions of all components used by wp.components.FontSizePicker and wp.blockEditor.LineHeightControl as experimental. Only migrate the components wp.components.FontSizePicker and wp.blockEditor.LineHeightContro to g2 using the new experimental g2 components. The migration of these components could happen directly without having experimental/__next versions of them first. They are not complex components we would just need to make sure all the props combinations we can pass to them render correctly when using g2 components.

Besides typography tools, global styles will have color tools, a color palette editor, and UI to navigate between settings of the different blocks.
So the plan is to have global styles with only typography tools using g2 and the other tools using the current UI components? cc: @shaunandrews