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).
For this Integration/Typography Tools project, I’ve split up the work into 4 key phases:
- Post Build
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.
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).
Once all the tasks are done, and the initial Gutenberg integration tests feel solid, we can move onto the “Integration” phase.
The “Integration” phase involves migrating all of the packages from the G2 Components repo into the Gutenberg repo. The initial packages would be
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.
The G2 system packages would live as dedicated packages within Gutenberg, with a slight adjustment to their names.
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:
The only G2 package that differs from the above-mentioned migration would be
The idea is to move all of the code from
@wp-g2/components directly into
The G2 code will mostly be separated into clearly marked directories (most likely
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
- UI that can directly replace existing components (current
- UI that to live alongside existing components, but in a “dormant state“, activated with the “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
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!
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
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.
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.
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!).
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”.
The “post build” phase involves us moving the second (and final) patch of components over from G2 to Gutenberg.
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.
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!