Twig: Create Drupal Theme

[justintemps]

Scope

As per @ademarco's comment below:

Create a minimal Drupal base theme, that:

• Provides a pre-built set of assets
• loads all needed CSS and JS files by default
• Exposes all components of the ILO Design System Twig Component Library as UI Patterns, using https://www.drupal.org/project/wingsuit_companion

Developers can then extend this theme with their own project's theme, and start using it.

Background

Drupal Developers are having a hard time incorporating the Design System. The current docs ask them to create a custom theme and then add the design system at a very low level, which requires them to do things like configure rollup, move assets around, bundle JavaScript and do other things that Drupal developers ordinarily don't have to do.

After some discussion, it seems like the best way to put the Design System Twig Library at their disposal is by building a Drupal Theme ourselves and then distributing it on Composer or something. Ideally, this would allow Drupal developers to simply import the theme and then use the components as libraries. That would make the library a lot easier to start working with while concealing the internals so they wouldn't have to worry about it.

This would also protect them from breaking change to the underlying Design System. For example, right now the developers are counting on the file system of the package not changing, because they need to know where the components are so they can move them from node modules into other places. But file system changes to an npm package ordinarily shouldn't be a breaking change, because that shouldn't be the interface for the package.

[bashlk]

@justintemps We were not able to figure out what this issue is about. The title refers to the docs, but we couldn't find a rollup configuration outlined in any of the docs.

[justintemps]

@bashlk you can see the example rollup config here: https://twig.ui.ilo.org/?path=/docs/getting-started--page

[bashlk]

I had a chat with @ademarco and @bircher about how we can distribute the twig version of the design system to Drupal developers. Here is what I was able to gather and I will also try to summarize the problem space here.

Currently we don't have a "Drupal native" way of distributing the design system. We publish the twig version of the design system as a npm package and provide some basic instructions for Drupal developers on how they can setup a bundler and a custom Drupal theme to consume that npm package (https://twig.ui.ilo.org/?path=/docs/getting-started--page#installation). This is not very convenient for the Drupal developers and some developers that @justintemps has reached out to have already expressed reluctance in adopting this since it involves a lengthy setup.

IMO what we should aim to have is something that a Drupal developer can just install and start using immediately without having to configure any tools. From what I understand so far, this means that the design system should be distributed as a Drupal theme.

The guys mentioned several ways in which we can build this theme. I believe the preferred approach was a theme that uses the UI patterns module (https://www.drupal.org/project/ui_patterns) together with the wingsuit module (https://www.drupal.org/project/wingsuit_companion) which allows a wingsuit project like what we have right now to be fed into the UI patterns module which would then be usable by a Drupal developer directly without any extra setup.

Another approach we talked about was having a starter kit theme instead (https://www.drupal.org/docs/core-modules-and-themes/core-themes/starterkit-theme) so that instead of having a complete theme, we provide only a base from which a developer can bootstrap a theme and start customizing it. Another approach considered was levering single directory components module (https://www.drupal.org/project/sdc) which was recently merged into Drupal core and supports consuming components in a similar structure to the wingsuit project we have now.

Since I am unfamiliar with Drupal terminology, it is not clear to me how all these pieces join together and whether the summary I wrote above is correct. @bircher @ademarco can you please elaborate on this?

So additional points we need to consider are how updates to the design system can be provided to the theme and how the theme can be adopted by an existing site. For reference, this is the custom theme that the developers of the new ilo.org site have used (https://github.com/international-labour-organization/ilo-org-drupal/tree/59cae93090cf9deda1fc83b715704efedcc6709d/docroot/themes/custom/ilo)

[bashlk]

Related to this issue is the issue of testing the twig version of the design system (#455). Based on the quick chat with @ademarco, if we go ahead with creating this theme, we will be able to spin up a minimal instance of Drupal with the theme and run the tests against that.

[ademarco]

I would go for a minimal Drupal base theme, that:

1. Provides a pre-built set of assets
2. loads all needed CSS and JS files by default
3. it's not opinionated on header, footer, tabs, etc. i.e. developer using the theme will need to incorporate these elements in their project as needed
4. Exposes all components of the ILO Design System Twig Component Library as UI Patterns, using https://www.drupal.org/project/wingsuit_companion

Developers can then extend this theme with their own project's theme, and start using it.

[justintemps]

Hey @ademarco that sound perfect. Would this be something that Drupal developers could easily integrate into pre-existing projects?

[ademarco]

On an existing project they would need to then use this as base theme, rather than whatever they are using. This might be a challenge, if you have a more concrete example I can make sure that the theme uses the same base theme that they are using, so that it will be easy to plug it in, assuming they started from one of Drupal core's themes. If the did not, then we should maybe consider to distribute this as a module. Or both.

[ademarco]

@justintemps if this is the theme you are referring to, then we should be ok, since it's not based on any theme

https://github.com/international-labour-organization/ilo-org-drupal/blob/main/docroot/themes/custom/ilo/ilo.info.yml#L4

They would then just base their theme on ours.

[ademarco]

For example, having the components organised as patterns will help with removing these repetitions: having to attach the same libraries every time the image component needs to be used.

[justintemps]

Hey @ademarco the

@justintemps if this is the theme you are referring to, then we should be ok, since it's not based on any theme

https://github.com/international-labour-organization/ilo-org-drupal/blob/main/docroot/themes/custom/ilo/ilo.info.yml#L4

They would then just base their theme on ours.

This is actually the first project that would need to make this change: https://github.com/international-labour-organization/gcsj-drupal

In terms of a deadline, I think this would need to be ready fairly soon, within the next month or so at least.

[bashlk]

@justintemps I don't have access to the project you linked. I am not sure whether @ademarco does either.

Scratch that - was not logged in 🤦‍♂️

[ademarco]

@justintemps could we maybe create a repo called ilo_base_theme? I'll then push my work on that repo.

[justintemps]

@ademarco the repo is created

[justintemps]

Hey @ademarco it seems like the scope of this ticket has been completed. Should we close?