Integration Guide: Drupal 10

Drupal 10 Starter Guidance

Use this if you want a fast, production-focused starting point for integrating TXDS into a custom Drupal theme.

Asset links:

1. Copy assets into your theme

Required files:

css/design-system.css
js/design-system.js
css/agency-brand.css (optional overrides)

2. Register one Drupal library

In your_theme.libraries.yml:

txds:
  css:
    theme:
      css/design-system.css: {}
      css/agency-brand.css: {}
  js:
    js/design-system.js: {}

3. Attach globally in theme info

In your_theme.info.yml:

libraries:
  - your_theme/txds

Use per-page attachment only if you need strict asset scoping.

4. Apply TXDS classes in Twig templates

Use the component markup from this site directly in your Twig overrides.

{# node--article.html.twig #}
<article class="txds-card">
  <div class="txds-card__body">
    <h2 class="txds-card__heading">
      <a href="{{ url }}">{{ label }}</a>
    </h2>
    <p class="txds-card__text">{{ content.body }}</p>
  </div>
</article>

5. Map Drupal messages to TXDS alerts

{# block--system-messages-block.html.twig #}
{% for message in messages %}
  <div class="txds-alert-banner txds-alert-banner--{% if message.type == 'error' %}danger{% elseif message.type == 'warning' %}warning{% else %}information{% endif %}" role="{% if message.type == 'status' %}status{% else %}alert{% endif %}">
    <span class="txds-alert-banner__icon" aria-hidden="true">{% if message.type == 'status' %}ℹ{% else %}⚠{% endif %}</span>
    <p class="txds-alert-banner__text">{{ message.text }}</p>
  </div>
{% endfor %}

6. Brand via tokens only

In css/agency-brand.css:

:root {
  --txds-color-primary-50: #1a5276;
  --txds-color-primary-60: #0e2f44;
  --txds-font-family: 'Merriweather', Georgia, serif;
}

Keep TXDS source files unchanged. Put all brand changes in override CSS.

7. Drupal behavior contract for JS components

Keep required data-txds-* hooks and aria-* attributes from component examples.
Ensure TXDS behavior runs after Drupal Ajax replacements.
Re-test accordion, modal, mega menu, and mobile menu on Ajax-rendered regions.

Definition of done

TXDS library loads on all intended routes.
Components render from Twig without markup drift.
Keyboard navigation and focus states work.
Color contrast and landmarks pass accessibility checks.
Agency token overrides apply with no edits to core TXDS files.