Overview: Features

[eliot-akira]

Create a frontend style framework with the goal of:

• Setting standards for good UI practices
• Providing basic helper classes to speed up frontend development time
• Bringing consistency to our plugin frontends
• Making our plugin styles less likely to interfere with other aspects of our users' sites, and making it easier for users to restyle themselves
• Perhaps bringing us a step closer to being able to provide users with a settings panel to manage colours and other aspects of our plugins' frontend interfaces, something perhaps like this

---

• This could be implemented as an NPM module

• PostCSS plugins that could help us with prefixing: postcss-prefixer, postcss-variables-prefixer, postcss-simple-vars

• Early version of the framework in use in a functionality plugin for a client here

---

• Component-ize the styles so that they can be selectively loaded as they're needed: buttons, tables, tag pills etc.

• Pair this with a React component framework eventually

(Description based on TangibleInc/framework#1)

[eliot-akira]

@juliacanzani @nicolas-jaussaud

There are many aspects we could discuss about the architecture and features of the Design module. The current initial project setup is just a rough draft, and anything can be changed or removed. A few thoughts I had while preparing..

---

The article proposing standardized design tokens in WordPress is good reference. It takes lessons from the trends of atomic CSS and Tailwind, in particular the use of utility classes, variables, and naming conventions. This approach fits well with my own Sass practices across various projects over the years, and from what I've seen in open-source projects - including the Bayside Features example.

One thing about that example, at least for my own use case, is that it outputs a stylesheet with many unused CSS variables. WordPress core does this now too. Personally I'd rather use Sass variables, which disappear after compilation if they're not used. Ideally, I'd love it if the Design module supported this approach. And other ways to load features selectively.

---

About having a settings panel to manage colours and other aspects of UI styling - in order to achieve this, the CSS/Sass variables need to be dynamically generated from the settings.

With the current project setup, the final CSS bundle is built by Tangible Roller, the same way other Tangible plugins and modules do. It might be more flexible to use the new CSS engine (TangibleInc/template-system#101), which can dynamically compile things in the browser, for example when saving within such an admin settings panel. That way, the CSS bundle can be regenerated when someone changes the variables.

---

An interesting aspect of the current setup is that it uses wp-now to quickly start a local WordPress site for development and testing.

Unlike wp-env, which is what WordPress/Gutenberg projects use - and what we've been using for plugin testing, wp-now does not require installing Docker. It runs on PHP-WASM from the WordPress Playground project, so it only requires a JavaScript runtime such as Node. I like that it's self-contained and much quicker to get started. If this approach works well, I'll incorporate it more into our workflow, plugin/module setup, testing, etc.

---

About encapsulating our plugins' styles - in addition to prefixing classes and variables, which will protect users' styles from our own, we need a way to selectively reset styles, to have a consistent starting point for styling. This will ensure that elements are styled properly in any context, such as the WordPress admin screen, page builders, frontend themes.

I've included a reset stylesheet based on Tailwind's. As you can see from the HTML5 test page, it's quite a strong reset compared to other popular solutions like normalize.css, so we'll likely need to adjust it for our purposes.

From experience I know we need a strong reset like this, to protect against overly eager CSS styles, for example Beaver Builder's crazy selector like .fl-builder * > *. This is a common problem with CSS as a language, the "cascading" aspect, related to the problem of inheritance in object-oriented programming; in contrast, using a reset + utility classes ensures that effects are atomic and isolated.

---

For now, the Design module is described as providing "building blocks for creating design systems". But aside from general-purpose building blocks, we'll be creating a specific design system for Tangible plugins. So eventually we'll need to draw the line, to separate the base layer with generic parts that users can import to create their own design systems.

About "making it easier for users to restyle" - I love that aspect of libraries like React Aria, the usefulness of "headless" templates that are completely unstyled, with accessible patterns and structures to build your own styled components.

[juliacanzani]

This all sounds great! I'm struggling a bit to get set up to work locally, I'm getting some errors around missing dependencies when trying to run dev (Error: Cannot find module 'fs/promises'), and haven't been able to get wp-now to launch so I've set up the repo as a plugin on a local WP site instead. Node also seems to not appreciate the datetime-as-version-number approach: it throws this error npm ERR! Invalid version: "20240403" which clears up when the package.json version is manually adjusted to 1.0.0

I might bug Nico for help this week!

[eliot-akira]

Ah OK, no problem - please feel free to create new issues in this repository.

About fs/promises not being available, it sounds like the installed version of Node needs to be updated. I like to use a tool called n-install to manage multiple versions of Node (how to install here). (Or it might be simpler to download the newest version from Node's homepage and overwrite the existing install.) I think wp-now requires Node v18, but I recommend the newest LTS (long-term support) version - currently 20.12.1.

• 2

About using date-time as version number, it's actually only used internally by the module loader, so we can change it in package.json to YYYY.MM.DD to meet the syntax that npm expects. And I'll update version.js, a little script that updates the version number in a few files that use it.

• 3

---

On a somewhat related topic: CodeMirror, the library that the new template editor uses, defines its themes as JavaScript objects; unlike in the previous version where themes were in plain CSS. This change was made to isolate and protect the editor styles, so that it's not broken by its surrounding context (the site using the editor) and vice versa. We will probably go in a similar direction.

A disadvantage of this approach is that it's no longer so simple to create and edit the editor's themes. It now requires some JS knowledge and a build system.

For our purposes, I wanted to make the themes easier to edit somehow for L&L users as well as for Tangible team members. Many of the themes need improvement, more or less, and it would go faster if people could edit them without needing a local dev setup to build the editor's JS file. I think I will convert the themes to JSON format and load them dynamically.

Anyway, in general I'm trying to modularize the plugin framework and template system, so that other people can work on modules independently. And I'm working on simplifying the plugin/module project setup, so that it's easier to get started and contribute to their development.

[eliot-akira]

OK, I made the changes mentioned above. To update your local project, it should be as simple as running git pull, as long as you don't have any conflicting changes.