From 8da8a708393ba978ca3a85bddd8e634aff4c063e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Albert=20Juh=C3=A9=20Lluveras?= Date: Mon, 13 May 2024 18:26:50 +0200 Subject: [PATCH] Update docs about blocks styling to clearly state global styles are the recommended approach (#47269) * Update docs about blocks styling to clearly state global styles are the recommended approach * Markdown formatting fixes * Add changelog file * Add styling the Product Price block example * Markdown formatting fixes (II) * Update plugins/woocommerce-blocks/docs/designers/theming/README.md Co-authored-by: Patricia Hillebrandt * Update plugins/woocommerce-blocks/docs/designers/theming/README.md Co-authored-by: Patricia Hillebrandt --------- Co-authored-by: Patricia Hillebrandt --- .../docs/designers/theming/README.md | 71 +++++++++++++++---- .../designers/theming/cart-and-checkout.md | 2 + .../docs/designers/theming/filter-blocks.md | 2 + ...e-woocommerce-blocks-theming-global-styles | 4 ++ 4 files changed, 64 insertions(+), 15 deletions(-) create mode 100644 plugins/woocommerce/changelog/update-woocommerce-blocks-theming-global-styles diff --git a/plugins/woocommerce-blocks/docs/designers/theming/README.md b/plugins/woocommerce-blocks/docs/designers/theming/README.md index ac14bf5a114..38ec8261b5e 100644 --- a/plugins/woocommerce-blocks/docs/designers/theming/README.md +++ b/plugins/woocommerce-blocks/docs/designers/theming/README.md @@ -4,12 +4,53 @@ This page includes all documentation regarding WooCommerce Blocks and themes. ## General concepts +### Global styles + +WooCommerce blocks rely on [global styles](https://developer.wordpress.org/themes/global-settings-and-styles/styles/) for their styling. Global styles can be defined by themes via `theme.json` or by users via Appearance > Editor > Styles and offer several advantages over plain CSS: + +* Better performance, as only the required CSS is printed into the page, reducing the bundle size to render a page. +* Can be easily customized by users via the UI. +* Gracefully handle conflicts between plugins and themes. +* Are not affected by markup or class name updates into individual blocks or components. +* Don't depend on a specific nesting order of blocks: users can freely move blocks around without styles breaking. + +#### Example + +For example, let's imagine you are building a theme and would like to customize the Product Price block styles, you can do so by adding these properties in your `theme.json`: + +```JSON +"styles": { + "blocks": { + "woocommerce/product-price": { + "color": { + "background": "#00cc00", + "text": "#fff" + }, + "typography": { + "fontStyle": "italic", + "fontWeight": "700" + } + } + ... + } + ... +} +``` + +Before | After +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- +Product Collection block showing the Product Price block with default styles | Product Collection block showing the Product Price styled with background and text colors and italic and bold typography + +You can find more [documentation on global styles](https://developer.wordpress.org/themes/global-settings-and-styles/styles/) in developer.wordpress.org. You can also find the [list of WooCommerce blocks and their names in the docs](../../block-references/block-references.md). + ### Block and component class names +**Important: we strongly discourage writing CSS code based on existing block class names and prioritize using global styles when possible. We especially discourage writing CSS selectors that rely on a specific block being a descendant of another one, as users can move blocks around freely, so they are prone to breaking. Similar to WordPress itself, we consider the HTML structure within components, blocks, and block templates to be “private”, and subject to further change in the future, so using CSS to target the internals of a block or a block template is _not recommended or supported_.** + WooCommerce Blocks follows BEM for class names, as [stated in our coding guidelines](../../contributors/coding-guidelines.md). All classes start with one of these two prefixes: -- `.wc-block-`: class names specific to a single block. -- `.wc-block-components-`: class names specific to a component. The component might be reused by different blocks. +* `.wc-block-`: class names specific to a single block. +* `.wc-block-components-`: class names specific to a component. The component might be reused by different blocks. The combination of block class names and component class names allows themes to style each component either globally or only in specific blocks. As an example, you could style all prices to be italics with: @@ -37,12 +78,12 @@ Some of our components have responsive classes depending on the container width. Those classes are: -| Container width | Class name | -| --------------- | ----------- | -| >700px | `is-large` | -| 521px-700px | `is-medium` | -| 401px-520px | `is-small` | -| <=400px | `is-mobile` | +Container width | Class name +----------------|------------ +\>700px | `is-large` +521px-700px | `is-medium` +401px-520px | `is-small` +<=400px | `is-mobile` As an example, if we wanted to do the Checkout font size 10% larger when the container has a width of 521px or wider, we could do so with this code: @@ -69,16 +110,16 @@ WooCommerce Blocks avoids using legacy unprefixed classes as much as possible. H ## Blocks -- [Filter blocks](filter-blocks.md) -- [Cart and Checkout](cart-and-checkout.md) +* [Filter blocks](filter-blocks.md) +* [Cart and Checkout](cart-and-checkout.md) ## Other docs -- [Product grid blocks style update in 2.7.0](product-grid-270.md) -- [Class names update in 2.8.0](class-names-update-280.md) -- [Class names update in 3.3.0](class-names-update-330.md) -- [Class names update in 3.4.0](class-names-update-340.md) -- [Class names update in 4.6.0](class-names-update-460.md) +* [Product grid blocks style update in 2.7.0](product-grid-270.md) +* [Class names update in 2.8.0](class-names-update-280.md) +* [Class names update in 3.3.0](class-names-update-330.md) +* [Class names update in 3.4.0](class-names-update-340.md) +* [Class names update in 4.6.0](class-names-update-460.md) diff --git a/plugins/woocommerce-blocks/docs/designers/theming/cart-and-checkout.md b/plugins/woocommerce-blocks/docs/designers/theming/cart-and-checkout.md index 2e12ca7d70d..7a4834da827 100644 --- a/plugins/woocommerce-blocks/docs/designers/theming/cart-and-checkout.md +++ b/plugins/woocommerce-blocks/docs/designers/theming/cart-and-checkout.md @@ -1,5 +1,7 @@ # Cart and Checkout Blocks Theming +**Important: we strongly discourage writing CSS code based on existing block class names, prioritize using global styles when possible. We specially discourage writing CSS selectors that rely on a specific block being a descendant of another one, as users can move blocks around freely, so they are prone to breaking. Similar to WordPress itself, we consider the HTML structure within components, blocks, and block templates to be “private”, and subject to further change in the future, so using CSS to target the internals of a block or a block template is _not recommended or supported_.** + ## Table of Contents - [Buttons](#buttons) diff --git a/plugins/woocommerce-blocks/docs/designers/theming/filter-blocks.md b/plugins/woocommerce-blocks/docs/designers/theming/filter-blocks.md index 14cfd3ec80d..261e1112f4f 100644 --- a/plugins/woocommerce-blocks/docs/designers/theming/filter-blocks.md +++ b/plugins/woocommerce-blocks/docs/designers/theming/filter-blocks.md @@ -1,5 +1,7 @@ # Filter blocks +**Important: we strongly discourage writing CSS code based on existing block class names, prioritize using global styles when possible. We specially discourage writing CSS selectors that rely on a specific block being a descendant of another one, as users can move blocks around freely, so they are prone to breaking. Similar to WordPress itself, we consider the HTML structure within components, blocks, and block templates to be “private”, and subject to further change in the future, so using CSS to target the internals of a block or a block template is _not recommended or supported_.** + ## Price slider accent color The Filter by Price block includes a price slider which uses an accent color to show the selected range. diff --git a/plugins/woocommerce/changelog/update-woocommerce-blocks-theming-global-styles b/plugins/woocommerce/changelog/update-woocommerce-blocks-theming-global-styles new file mode 100644 index 00000000000..b3bb84c470f --- /dev/null +++ b/plugins/woocommerce/changelog/update-woocommerce-blocks-theming-global-styles @@ -0,0 +1,4 @@ +Significance: patch +Type: dev + +Update docs about blocks styling to clearly state global styles are the recommended approach