Standard theme blocks

[bakura10]

Hi !

@kinngh raised a great concern on Twitter (https://x.com/kinngh/status/1832194863057485917) about apps and themes.

Historically, integrating apps within themes is nearly impossible. Maestrooo recently released an app on the store and one challenge was to visually integrate with hundreds of themes.

I've thought of various solution (such as detecting the theme in JS and injecting per-theme stylesheet) or setting a lot of classes on elements, hoping to have one that match the theme. But both approaches are not scalable and it is harder when you need to take into account multiple theme versions.

I believe theme blocks might answer this problem, so I wanted to share some ideas.

Standard theme blocks

Similar to standard metaobjects, Shopify could introduce a concept of standard theme blocks. A standard block would simply be a block that is required for all themes before being uploaded. A theme missing a specific block would show an error when being uploaded.

In addition, standard block must have a set of settings that are required (kind of an interface). This would be the contract between themes and apps, so that apps can know that they can at least access to this block with a given settings. Additionally, if there are more complex standard block (such as a product card), Shopify should provide guidelines (eg.: a product card rendered in the context of a product listing) to ensure that app devs can consume a standard block in the correct context).

Of course, theme devs would be free to add extra settings on such blocks so that they can achieve the desired flexibility for themes.

Examples

I thought of two examples that could be useful:

• Button. Required settings: "text", "link", "type" (submit, button, reset...), "style" (solid, outline)
• Product card. Required settings: "product"

I think that we should ask for app devs for more examples.

Usage

One challenge for app dev is that not all merchants would be on a compatible version. Maybe Shopify could re-introduce the deprecated theme variable in Liquid to allow app devs to introspect the theme:

{% if theme.supports_theme_blocks %}
  {% content_for 'block', type: 'button', settings: { content: 'Add to cart' } %}
{% else %}
  // Render a generic button
{% endif %}

Theme blocks currently does not support statically render theme blocks and pass arbitrary setting data, so this is an example syntax.

Potential issues

Shadow DOM is an awesome technology to isolate an app from the rest of the theme. I tend to use more and more Shadow DOM, Shopify is using it for the new dynamic button as well, and in overall I think Shadow DOM is vastly underused in Shopify app ecosystem.

The issue is that this approach would not work in the context of app blocks. Let's image an app block in a Shadow DOM:

<my-app-block>
  <template>
    {% content_for 'block', type: 'button' %}
  </template>
</my-app-block>

Even if the theme block from the app is rendered, it won't be styled, because the Shadow DOM does not inherit the styles from the root.

I think it would be great to have a solutions that also supports shadow DOM as they are really a great tool for helping isolate app code. Maybe standard blocks could have extra restrictions (such as having their CSS directly in the app block) but I'm not sure how it could work in practice.

Conclusion

Theme blocks can be a game-changer for app integrations that no longer rely on hacks. This probably complicates a lot of the theme blocks architecture, but taking into account the app from the start will probably help to gain further adoption.

[sadsciencee]

It's def needed for the level of interoperability Shopify clearly wants between themes and apps.

To add another "standard type", I copy paste a standardized media with desktop/mobile, image/video, crop adjust, ratio adjust and overlay controls about 40 times every custom theme I roll out.

One concern I have about standardized blocks is that in the past (and present), Shopify has at once been both too restrictive and too bulky with the standard types they roll out.

For example, the default color scheme in Dawn has options I rarely use in custom builds (shadow/outline) but is missing color rules I need all the time. I end up customizing the schemes for every build with 3-5 additional color settings added to schemes.

Another example would be the standard metaobject type. These are somehow too broad and too narrow at the same time. There are far too many types to build familiarity with so we will always be reference docs, but more often than not I find myself working for merchants with product categories that don't fit any of Shopify's taxonomies. Even if there is a standard metaobject for a category, I have yet to run into a situation where I didn't have to make my own manually because the default didn't fit the merchant's use case.

If Shopify is going to introduce standard block types, which I am strongly in favor of, it needs to be focused on composable primitives, not brittle presets.

[sadsciencee]

One thing that may work here is introducing a 'role' or 'key' value to setting schemas. Theme devs would be free to do what they need to do in any given theme section/block, but to opt-in to 'app compatibility mode' you would just need to specify the role of certain settings within a section.

The block definition has an optional 'app_role' setting. This role could be scoped under 'global' | 'section' | 'block' namepsaces. 'global' namespace would be more for brand settings like buttons, spacing, typography. 'section' namespace would allow composition of multiple blocks. 'block' namespace would be for core primitives.

So for example we could compose a 'hero banner' block namespace (title, subtitle, buttonsx2, alignment & spacing settings) with a 'art direction' block namespace

See example below for how I would implement this on block settings. In my perfect world, app devs could check for the theme's default block.product.tile role & if available, use the theme's liquid code, potentially populating the section values with app-defined content.

{
  "block": {
    "type": "product",
    "name": "Product",
    "app_role": "block.product.tile",
    "settings": [
      {
        "type": "product",
        "id": "product",
        "label": "Product",
        "block_role": "product"
      },
      {
        "type": "image_picker",
        "id": "image",
        "label": "t:sections.image-banner.settings.image.label",
        "block_role": "featured_media"
      },
     {
        "type": "text",
        "id": "badge_text",
        "label": "Badge Text",
        "block_role": "badge_text"
    ]
  }
}

[kinngh]

Opinion: This would lead to everyone using their own naming convention. It makes more sense to follow a more standard approach of "here's a data sheet that contains entries for elements like spacing, primary, secondary, tertiary buttons, etc" so button.primary would actually work across all themes.

This is why I suggested a Checkout UI Extensions like library, so <button variant="primary"></button> would be consistent across all themes.

The baseline here is setting up a list of standard elements that are needed for building a theme extension, like page width, button + variants, element spacing, etc.

[chiragramjibhaipatel]

for a baseline, we also need a standard breakpoints as well.

[sadsciencee]

Totally - I was thinking these would be similar to checkout extension/customer extensions targets - so Shopify would provide the keys and roles here.

[gideonb]

I don't think Shopify should be in the business of defining one set of breakpoints for all themes an apps, but I support the idea of a themes breakpoints being published in a JSON format that an app can read.

[tomatic]

Sorry if this is stupid, I may not have thought this through entirely.

To me it seems the problems integrating app blocks into themes stem mainly from an approach of trying to somehow match themes' styles/classes. This is of course next to impossible, given that the number of themes and theme versions isn't finite.

But app blocks can include their own style settings that would allow merchants to individually style elements to fit their theme, e. g. settings for foreground and background colors, borders, fonts, margins, padding, etc. You could even combine that with a dropdown of the most popular themes where each option would apply well-known classes/styles/settings presets to the app block's elements.

While this is certainly not ideal and also somewhat redundant, I'd say it beats trying to somehow auto-match a theme's styles. We do this for the app block of our app and it works quite well without being unmanageable in terms of the number of style settings in the app block.

Of course it would be nice to be able to slap a button into an app block and it'd just magically take on the styling of any theme that adheres to some yet to be defined standard. I just wonder if establishing such a standard A) is feasible and B) would be net-positive in terms of effort required for app developers.

[kinngh]

[Opinion]

1. Yes, adding in a lot of schema to the theme block would solve a lot of these issues, you're also limited to 100kb of Liquid, and a lot of your space is taken up by schema and conditionals which is a waste of that limit.
2. The need to match to the user's theme arises from the fact that some, if not most, theme block extensions need to feel native to the theme, instead of an something that was slapped on the page / template and it works
3. Giving merchants the ability to customize sections, beyond a certain point, is calling for problems. This is something the current iteration of Online Store 3.0 is going through and @bakura10 covered this extensively in his post about Upgrade concerns and usability.
4. Your case of building theme extension would satisfy your need of giving merchants the ability to customize, but there's a sizeable chunk of developers who exceed the 100kb Liquid limit and either have to fall back to Asset API or cut corners in optimization and performance that leads to a poor experience.

[tomatic]

Ah right, I forgot about that 100kb limit, that could definitely become an issue for some devs.

As for 2.: Don't disagree there, maybe I didn't make myself clear enough. My point was just that this is achievable by including styling settings in the app block's schema. But of course your other points wrt this approach still apply.

[kinngh]

Re: selective schema - makes sense for smaller blocks, for ones that are a little more complicated mess up the entire limit^

[chiragramjibhaipatel]

Sidenote:

Themes that are customised by developers, they are not utilising the theme's color schemes and adds their own styles etc directly to themes(due to delivery-time or expertise constraints). Creating a theme block for such themes looks impossible. Each theme is a different story.

Even though we scope out these usecases, there will be huge number of themes/stores which will get benefit from this.

[chiragramjibhaipatel]

@kinngh, 100% agree, this actually applies to everything across all the language/platforms. This in itself another topic, the only solution here is to have a qualified mentor for each developer. The self-taught developer will always gonna do wrong thing and uses merchant's themes as a playground.

@tomatic theme itself not supporting the color schemas in their updates is really weird.

[tomatic]

@kinngh Weird, yes, but that's the messy reality. Theme in question is Masonry v6.1.2 from September 2024.

[kinngh]

[Opinion] The whole self-taught developer is a lousy excuse at best. I understand it's a time consuming process to stay up to date with everything, but even I am a college dropout solo developer working with merchants, building apps and doing a lot of open source. I don't think I have to put my credentials out there, but the day we move on from making excuses to pulling up with solutions is when we get past these unnecessary discussion of 'but what about the _____ group'. There's changelogs, there's announcements, there's newsletters and a lot of other resources to really be updated.

The problem is most developers only wake up when the hammer comes down and challenges their current state of coasting along (I get it customer support is a huge challenge too) and then the panic sets in for them, which ruins things for the set of developers who actually spend the time to read through the docs and build things to be on the bleeding edge at all times, resulting in net progress being delayed significantly.

We can go much deeper into this discussion and have 0 net progress there so I will not be spending more time on this specific area of the thread.

[bakura10]

Regarding color schemes, I'm also a bit culprit for that. At Maestrooo we've only updated Prestige (our best selling theme). This is indeed not a required update, and one of the reason we did not do it for Impact for instance is the fact that you can't connect dynamic source to color schemes. In Impact we have a strong focus on colors, and the whole concept around our demo stores is to have different product pages where many colors change from product to product by connecting a product "accent" color. Replicating this with color scheme would involve creating nearly a hundred color schemes.

We considered upgrading it, but we realized that this aspect of our demo stores was a big selling point for Impact, so we decided not to upgrade this theme.

Some use cases are hard to achieve with color schemes, and that might be the reason Shopify did not push for it (but I love using color schemes on Prestige, and all our next themes will be built with color schemes).

[tomatic]

@bakura10 Oh, that's a great point, wasn't aware of that. It'd probably be pretty complex for Shopify to hook color schemes up to dynamic sources, if it'd even make sense. You can already hook up different color schemes to different templates, so there is a way to do that, just maybe not as elegant and with more overhead.

[bakura10]

Hi everyone,

Thanks a lot for all the great comments and ideas.

@kinngh experimented with a solution based on classes (https://github.com/kinngh/shopify-theme-elements) but I believe this option should be avoided, because it completely ignores Shadow DOM (which is really something that app dev should use more, so we should definitely take into account Shadow DOM for this).

@t-kelly (from Archetype) suggested the usage of CSS variables (https://x.com/thommaskelly/status/1832900528642158772) which is a way better approach as it will works well in context of Shadow DOM.

I also gave it some more thoughts.

CSS properties concept

As said, the main issue with using classes is that they won't work in shadow dom. So if an app block uses the shadow dom, even if you have the correct class, the styles won't be inherited as the shadow dom is scoped:

<my-app>
  <template shadowrootmode="open">
    <button class="{{ theme_class }}">Button</button> <= Won't be styled even with the correct class
  </template>
</my-app>

Shopify themselves will soon move to the Shadow DOM for their dynamic button, and took the approach of using CSS properties. You can find a reference here: https://shopify.dev/docs/storefronts/themes/pricing-payments/accelerated-checkout#accelerated-checkout-button-css-custom-properties

Which CSS properties should be define would require a bit of work, but I think we could start with:

• --theme-button-border-radius
• --theme-button-border
• --theme-button-box-shadow
• --theme-button-background-primary
• --theme-button-text-color-primary
• --theme-button-background-secondary
• --theme-button-text-color-secondary
• --theme-button-padding-inline
• --theme-button-padding-block

(I think using padding is better in the context of a generic button rather than line-height, as using padding allows to not break everything when the button goes over two lines ; which can happen in a context of a theme or app block)

The advantage of CSS properties is that they pierce through the shadow dom, so an app could have their own class (even in the shadow dom) and use those CSS properties. The nice thing is that an app could use the default value to fallback to an app-specific style:

<my-app>
  <template shadowrootmode="open">
    <style>
       .button {
          padding: var(--theme-button-padding-block, 10px) var(--theme-button-padding-inline, 4px);
          background: var(--theme-button-background-primary, #000000);
          color: var(--theme-button-text-color-primary, #ffffff);
          border-radius: var(--theme-button-border-radius);
          border: var(--theme-button-border, none);
          box-shadow: var(--theme-button-box-shadow, none);
       }
    </style>
    <button class="button">Button</button>
  </template>
</my-app>

This solution will only be able to style basic functionalities (background, radius, size...). More advanced effects such as hover transition will be harder, as some themes have pretty complex hover animations that relies on pseudo-element or extra element. But as most store traffic is mobile-only now, I think this is an acceptable workaround.

Using Shadow DOM

If we absolutely want to have the same style (including animation), another solution would be to force theme dev to have those building blocks (buttons...) as a shadow dom. Shadow DOM are web-compoentns that are completely isolated and self-defined, so for instance a theme dev could create a button.liquid snippet and have all the markup (including the CSS) as part of the component:

// button.liquid theme block in the theme

<theme-button>
  <template shadowrootmode="true">
    <style>
      button {
        /* Button styles */
      }

      button:hover span {
        /* Some crazy effects */
      }
    </style>

    <button>
      <span>Button</span>
    </button>
  </template>
</theme-button>

An app dev could then include this theme block, and have the exact same markup and CSS as the theme:

// app-block.liquid

{% content_for 'block', type: 'button', settings: { content: 'Add to cart' } %}

Open questions

• In both cases, how can Shopify enforce this for themes? Should Shopify has a stricter validation process with code review, or can this be automated? The CSS properties is probably easier to do, especially since theme developers can just define a bunch of extra properties without having to alter their own code (migrating to shadow dom for all buttons can be a huge task for some theme devs). But it is extremely important I think that app devs have also a strong guarantee that if a theme supports theme blocks, then it supports one or the other solution.
• Button is a perfect use case, but do we have some other use cases? Something like a product card is too complex, and can't really be represented as a set of CSS properties. Maybe a "text-field", "checkbox", "select", "badge" and "banner" would be great candidates?

[benjaminsehl]

This is such a great discussion — thank you @bakura10 for kicking it off, and everyone else for contributing.
Can't believe I missed this 2 weeks ago, but it's like you all have inception-ed this into my head … was having very similar discussions recently. A lot of overlapping ideas here that I think align.

1. There's definitely a future where we lean more into web components as a first class citizen — especially for more atomic level components, I could see this idea of "Standard theme blocks" really working (buttons, text, etc). There is an interesting parallel here with how the JS world has approached these things architecturally — this is like "Atoms" in Atomic Design, or "element level" blocks in approaches like Styled System
2. The direction of leaning into standard namespaces for CSS Variables is also very compelling — this was one of the main takeaways after first announcing the idea of "Style Settings" where there was clear room for improvement on our side to allow for more granular control by developers, while still offering merchants a nicer looking / more purpose built UI

This is a really great start and would love to talk more.

[gideonb]

I agree with @benjaminsehl that the atom or element level is probably the correct level to start. Button is probably one of the more complex elements I would want to attack. There's almost fractal complexity in a some of the very tiny pieces. I could write a thousand words on our price.liquid snippet. I think that some of these tiny-but-complex items would be best as liquid snippets with baseline standard arguments:

button.liquid (text, link)
text-link.liquid (text, link)
badge.liquid (text)
styled-html.liquid (markup)
price.liquid (amount)

Forms get more complicated:

text-input.liquid (placeholder, label)
checkbok.liquid (text[optional], state[default, selected, disabled])
radio.liquid (text[optional], state[default, selected, disabled])
select.liquid (options[array], selected_index[optional])

I think all these liquid elements should have slots for class and attributes. Slots should default to the core element but in cases where there needs to be a wrapper the theme should define both wrapper and core slots. For the form elements you'll need id, name and so on. Those could be passed in a attributes on the core input element or defined as explicit arguments.

Then you have the pieces that are smaller than the atoms, the physics of the design system. Colors, sizing, spacing, shadows, rounding, line-height, etc. A lot of these would work as css variables. Their values are often contextual and you get that for free with css variables. Using the naming pattern from @bakura10 you might have these as a minimal set:

--theme-grid-margin
--theme-grid-gutter
--theme-color-background
--theme-color-text
--theme-color-link
--theme-color-primary
--theme-color-opposite
--theme-border-radius
--theme-shadow
--theme-animation-ease

You can actually get a lot of style from a few key pieces. I really think @bakura10 is onto something here.

[PaulNewton]

Theme blocks currently does not support statically render theme blocks and pass arbitrary setting data, so this is an example syntax.

We can now pass params to to static blocks https://shopify.dev/changelog/passing-parameters-to-static-blocks
{% content_for "block", id:"slide-1", type:"slideshow", color: "#F00" %} > inside blocks/block.liquid > {{ color }}
https://shopify.dev/docs/storefronts/themes/architecture/blocks/theme-blocks/static-blocks#passing-data-to-static-blocks
Dynamic-blocks still out of luck it seems; e.g. {% content_for 'blocks' %} .

[bakura10]

This is a nice idea, and something I've tried as well, but unfortunately it does not cover lot of use cases. First, it enforces a convention on the naming that you can't really have everywhere (we have compatibility issues, you took the easy path with an entire new theme, but please remind that we can't do that for premium themes and we have to handle backward compatibility to avoid breaking merchants store in the automatic upgrade, so renaming settings is not possible for us). Also, you're assuming that the section controls the number of items per row. It's not always the case, it can be a nested block.

Additionally, you might have some sections that have different setting on mobile. For instance, one common use case we have on our section is a setting that controls the mobile independntly, to decide if the items must be stacked or not, which affect their size.

I've done a suggestion in the past, but what would be nice and would map well to the "context" is to be able to pass custom context:

// In a section or a block

{% content_for 'blocks', context.columns: section.settings.items_per_row %}

Then each block would be able to get the closest context:

{{ block.context.columns }}

What is really nice with this system is that it allows a blocks to get the "closest" context, and therefore have override.

[PaulNewton]

assign sizes_attribute = '(min-width: 750px) [card_size]vw, 100vw | replace: '[card_size]', card_size

👀 [card_size]vw, 100vw | replace: '[card_size]', card_size
[card_size]vw👀😔
I winced so hard reading that.
Making in-template custom template interpolation is an anti-pattern in the string-parsing no-no category.
It's fragile by trying to be too clever increasing support burden and decreasing DX.
Something to be avoided til a last resort not embraced as a first class pattern.
Only do those types of things as a last resort for complicated systems , such as shortcodes, not because of built in disfunction.
It's the type of ivory tower pull up the ladder idea merchants should NEVER be exposed to as a default coding style.

So what anyone trying to develop or customize themes with non-linear sections now has to JUST KNOW™ such shin kickers exist and MUST KNOW they have to use shinguard#51 justsu because the idea of message passing was too hard for SHOP to figure out ?!?

I know it's a flyby forum post so we play fast and loose with syntax sometimes, but is it kind of a big fat hint that the example code is subtly broken:

assign card_size = 100.0 | divided_by: 5
assign sizes_attribute = '(min-width: 750px) [card_size]vw, 100vw | replace: '[card_size]', card_size

Outputs: (min-width: 750px) [card_size]vw, 100vw | replace:
Because of the missing single-quote escape, when fixed:

assign card_size = 100.0 | divided_by: 5
assign sizes_attribute = '(min-width: 750px) [card_size]vw, 100vw' | replace: '[card_size]', card_size

Outputs (min-width: 750px) 20vw, 100vw

Sure the missing single-quote should be catchable by the lsp or a linter, if some person has good tooling that is at the liquid step or frontend step checking rendered css/attributes that is.
But can a linter warn when (min-width: 750px) [card_size]vw, 100vw with a literal text of [card_size] ends up being rendered , or (min-width: 750px) vw, 100vw that lacks a value.
So to protect against moving parts failing from shinguard#51 we get yet another moving part by having to use shinguard#267defaultfilter-fu. Barnacles peppered everywhere is the sign of a pattern of a systemic issue.

More parts == more things to go wrong, and that type of string gymnastics is high friction to debug when it does go wrong.

We need escape hatches for reality, not byzantine abstractions from backend-engineering's agenda for scoping having lost the plot for a frontend system.

Otherwise just make it clear in the doc that needing non-linear sections, or passable context , etc etc is an indicator of when a store must leave the online-sales channel and make heavy investment into a custom storefront.

[msev]

I have the impression that, as it stands, making a tab system with theme blocks is tedious...
To make a tab system, we need to loop 2 times:

• once for tabs (buttons to activate tabs)
• a second time for the content of each tab

But as it is, it's impossible to differentiate between the 2 types of loop:

<ul role="tablist" aria-label="XXX">
  {% content_for 'blocks' %} <-- A
</ul>

<div>
  {% content_for 'blocks' %} <-- B
</div>

A should contain the button for each tab:

<li role="presentation">
  <button type="button" role="tab">Tab 1...</button>
</li>

B should contain the contents of each tab:

<div role="tabpanel">
  Content of tab 1...
</div>

If we could pass custom properties when calling {% content_for 'blocks' %}, we could easily create this tab system.

[bakura10]

Shadow DOM and slots solve this very elegantly.

[msev]

yes @bakura10, with Shadow DOM it's possible, but it would have been great to have a 100% liquid solution, as is currently possible with Section blocks.