Contrib.social

Convert CivicTheme components to use Single Directory Components

Open on Drupal.org →
Created on 25 March 2025, 11 days ago

Problem/Motivation

Single Directory Components have been stable in core since 10.3. Single Directory components.

SDC (currently) are the only types of components supported by core and by extension the only types of components that can be used with Experience Builder.

CivicTheme wants to support and provide a component based theme which works with Drupal CMS and Drupal 11 and a Single Directory Components architecture is the way to do this.

What are Single Directory Components (SDC)

Single Directory components bundle together the required html, css and JS into one directory so that everything you need to render a complete component on a page is contained within that directory.

For more information on Single Directory Components see the quick start guide.

Proposed resolution

Drupal CivicTheme

  1. Build the CSS for components in UI Kit and remove build system from base theme
  2. Create component validation system to ensure validation requirements are met
  3. Update Drupal templates to ensure we are including all the props for SDC components

Drupal Sub-Theme

  1. Update the build system for compiling SASS from UI Kit and splitting CSS into each component directory
  2. Update the build system for copying in components from UI Kit to SDC
  3. Create script to generate SDC component YML
  4. Package up the AI scripts to assist site developers to update their themes to SDC and generate YML files
  5. Update documentation for upgrade process, for new instructions for development of drupal theme and components

UI Kit

  1. Setup UI Kit to develop two sets of components
  2. Copy across twig components to SDC directory and update namespace to be SDC compatible
  3. Build the CSS for components in UI Kit and remove build system from base theme
  4. Update the build system for compiling SASS from UI Kit and splitting CSS into each component directory
  5. Update netlify to allow the publishing of two different storybooks for testing
  6. Create diffy system to compare visually twig components and SDC components to ensure they look exactly the same
  7. Update test structure to share tests between existing components and SDC components
  8. Update UI Kit to develop SDC components and create second storybook

Remaining tasks

Development for this project has begun at the following places:

UI Kit SDC project branch development

Drupal Theme SDC (note no development has taken place yet)

How are we going to handle existing sites

With the CivicTheme 1.10 → release where we handled the storybook upgrade via an upgrade script, we also intend the handle upgrades of sub-theme's and their components in the same way.

The script will handle two processes:
- Standard update script which will add and updating the build system to support SDC requiremnets (html, css and JS all contained within the same directory) and theme files in the sub-theme
- LLM / AI script to assist with extraction of properties from components and the creation of SDC compatible components, our development is also leaning on this and use of LLM for converting existing code has been fairly successful so far

🌱 Plan
Status

Active

Version

1.10

Component

Code

Created by

🇦🇺Australia RichardGaunt Melbourne

Live updates comments and jobs are added and updated live.
Sign in to follow issues

Comments & Activities

  • Issue created by @RichardGaunt
  • Comment 11 days ago →
    fionamorrison23
  • Comment 11 days ago →
    fionamorrison23
  • Comment 11 days ago →
    🇦🇺Australia RichardGaunt Melbourne
  • Comment 10 days ago →
    🇦🇺Australia RichardGaunt Melbourne
  • Comment 10 days ago →
    🇦🇺Australia alex.skrypnyk Melbourne

    Hi team,

    It is great to see this plan.

    I'd like to question/clarify a couple of things:

    1. Currently, it is possible to override a part of the component, a whole component or create a custom component in the sub-theme. This allows to only override parts of components with a minimum blueprint and, at the same time, rely on upstream. This makes CT-based sites easy to maintain, because only a specific set overrides would need to be supported. Could you please elaborate how this feature change?

    2. Currently, the UI kit provides a framework-agnostic styles and markup (yes, Twig is framework-agnostic as any other templating language; it just happened that Drupal and Wordpress uses Twig as well). The UI kit also does not have any "Drupalisms" in it making it usable in other frameworks. Reading the plan above, it looks like that the "Drupalisms" will be added to the UI Kit. Has an alternative been considered? For example, to have a converter from the UI Kit into framework-specific packages, where UI Kit could have a pipeline that would extract the props from the variables and blocks in Twig and put them into a `[name].component.yml` file. With the current Twig implementation this would be trivial to do.
    The CT team put a lot of efforts to keep the UI Kit clean from "Drupalism" in the past and it would be a shame to see the framework-specifics to be added to it.

    3. The simplification of the atomic structure into a flat structure is the way other design systems are going these days. I suggest to still have 3 levels: 'tokens' (all the low-level components - base + atoms), 'components' (all the molecules and organisms), 'pages' (assembled pages - currently there is only `Page`).

contrib.social Blog FAQ Discussions
Production build 0.71.5 2024