[meta] Introduce a Theme Component Library

Created on 5 October 2012, almost 13 years ago

Updated 2 July 2025, 11 days ago

Problem/Motivation

One of the things to come from #1801582: Add a new, non-default framework-based theme to Drupal core → was the want to implement a system similar to Jacine's proposed Theme Component Library for Drupal 8 Core. While I'm not sure if we're going to have time to implement everything we need, I believe we can start and, if it doesn't make it into D8 Core, we can continue this in Contrib.

Proposed resolution

I think the steps to start are something as follows:

seems like we agree here?
Twig can use this issue :)
LETS GO!

Remaining tasks

Decide on & create item components
- menu
- item_list
- table
Decide on and create container components
- a title and a thingy (block, comment, etc)
- an administration page
Re-work all existing markup from core to use these components: (This task belongs to TWIG)

More from the original issue

The following is, what I believe to be, a brief high level overview of what the Component Library needs to do and what it should not do.

Jacine sums up what is looking to be accomplished brilliantly in her post (link above):

Components are usually a combination of containers and formats that make up custom UI elements. Examples of components include Tabs, Vertical Tabs, Form Widgets (like password confirm and machine name), Carousels, Accordions, etc. Components usually have recommended use cases for application. Their implementation can vary from CSS and JavaScript standpoint, but their markup is pretty standard.

The goal of a Theme Component Library is to provide the markup and let the theme handle the CSS and JavaScript

Provide a set of common markup patterns as wrappers to be called (button patterns, unordered list patterns, ordered list patterns, headers, def lists, form elements, etc…) with the goal of having one set of predictable, easy to override, semantic markup. Jacine has done a lot of great work on the demo page she put together already.
Provide an easy way for themes to override a specific pattern and have it apply to all patterns without the use of override functions.
Provide predictable, precise, and useful CSS classes based on SMACSS guidelines that are easy to override or remove, ideally without the need of lots of override functions.
Allow for components to ingest other components and template files (where appropriate).
Disallow, to the best of our ability, markup to be directly injected into a component from a theme function or for a theme function to output markup directly without using a template/component. This is extremely frustrating currently and continuing to allow this would defeat the purpose of the component library.
Provide development and UI hooks to allow developers and site builders to make use of the components through code or through UI
Provide development hooks to allow developers to add additional components to the Component Library
Provide a Style Guide menu callback with all components on screen (or divided between major groupings) to allow for easy theming
VERY SPECIFICALLY do not include any default CSS or JS for these components unless absolutely necessary (such as in the case of widgets). When default CSS or JS is needed, make sure it is as minimal as possible and very easy to override/remove, ideally without a process/preprocess function. Think Stark as the default theme for these components, not Bartik.
- This may seem like it's missing the point of the component library, but from a front end developer's perspective, this is precisely what we want; predictable, semantic, clean markup that's easy to override that doesn't come with a bunch of CSS or JavaScript that we need to wrangle into place. While it will make life harder for site builders or backend developers not seeing their vision 100% initially, the goal here is to make frontend's life easier. Additionally, doing it this way allows for Contrib to come in with themes/modules (the line will start to blur) that are style guides to style this all (opening up easy integration with Bootstrap or Foundation or Skeleton or whatever in Contrib).