New style utility API

What is a style utility?

Styles utilities are a common artefact of design systems. Examples:

• Bootstrap’s utilities: https://getbootstrap.com/docs/5.3/utilities/api/
• Tailwind in DaisyUI: https://daisyui.com/docs/utilities/
• Material’s styles: https://m3.material.io/styles
• Bulma’s helpers: https://bulma.io/documentation/helpers
• PatternFly’s utility classes : https://www.patternfly.org/utility-classes/about-utility-classes
• USWDS’s utilities: https://designsystem.digital.gov/utilities/
• ...

Each style is a set of mutually exclusive, self-descriptive, single-purpose, universal, CSS classes. Examples: Typography, orders, Colors, Spacing, Elevation....

Declaration

Create PROJECT.styles.yml file in your extension (themes, modules), a simple declaration could be:

color:
  category: "Text"
  label: "Color"
  description: "Convey meaning through color with a handful of color utility classes."
  links:
    - 'https://documentation.example.com'
  options:
    primary:
      label: "Primary"
      value: "text-primary"
    secondary:
      label: "Secondary"
      value: "text-secondary"
   ...
  library: my_theme/my_library

Another declaration for mode could be, in the same file:

color_mode:
  category: "Modes"
  label: "Color mode"
  kind: mode
  attribute: "data-bs-theme"
  options:
    light:
      label: "Light"
    dark:
      label: "Dark"

Usage

In Twig:

Before:

attributes.addClass('text-primary')
attach_library('my_theme/my_library')

After:

attributes.addStyle('color', 'primary')

In render array:

Before:

$build = [
  '#type' => 'container',
  '#attributes' => [
    'class' => [
      'text-primary',
    ],
  ],
  '#attached' => [
    'library' => [
      'my_theme/my_library',
    ],
  ],
];

After:

$build = [
  '#type' => 'container',
  '#styles' => [
    'color' => 'primary',
  ],
];