An agent can use the USWDS AI Components design registry to figure out it needs usa-input and usa-button. But that doesn't tell you how to build the form in Drupal. Does a Paragraph bundle already exist? Does it go in a theme region? Do you need a custom Twig template?

Drupal USWDS AI Components answers the implementation side. It's a companion registry that sits next to the design one and provides the Drupal layer: module mappings, paragraph types, theme regions, Twig names, preprocess functions, and Drush commands.

The Two-Registry Pattern

The system uses two registries that work together. The design registry tells the agent what to build. The Drupal registry tells it how to build it.

User asks: "Build a government contact form"

Step 1: Query uswds-ai-components (design registry)
  → Returns: "Use usa-input, usa-button, usa-form"
  → Gives: HTML patterns, when to use, a11y guidance

Step 2: Query drupal-uswds-ai-components (this registry)
  → Returns: "Form has no paragraph bundle.
              Use custom Twig template."
  → Gives: Template naming, preprocess function,
           Drush commands, config

We kept them separate on purpose. The design registry is CMS-agnostic, so it doesn't matter whether you're in Drupal, WordPress, or plain HTML. The Drupal registry adds the implementation layer. Same pattern would work for a WordPress USWDS registry later.

Implementation Types

Not every USWDS component maps to the same Drupal implementation path. The registry classifies each component into one of five types:

  • paragraph_bundle : A ready-to-use Paragraph type from the uswds_paragraph_components module. Examples: accordion, alert, card, modal, process list, step indicator, summary box. The agent can tell the developer to install the module and use the existing bundle.
  • theme_region : Placed via the USWDS base theme's region system. Examples: header, footer, banner, breadcrumb, search, side navigation. No custom code needed; the region already exists.
  • field_type : Provided by a contrib module as a field type. Example: data visualizations via the plotly_js module, which provides chart fields instead of USWDS's limited chart patterns.
  • twig_template : Requires a custom Twig template in the theme. Examples: button, table, form, text input, tag, link, icon, pagination. The registry tells the agent which template name to use and what preprocess function to write.
  • custom_module : Requires a custom Drupal module. Rare; most components fit one of the above paths.

The Drupal Module Ecosystem

Three modules make up the USWDS-on-Drupal ecosystem:

USWDS Base Theme

The uswds theme project provides 14 regions, USWDS CSS/JS libraries, and subtheme examples. The registry maps each USWDS component to the region where it belongs, so the agent knows that usa-banner goes in the header_top region, not in a content block.

USWDS Paragraph Components

The uswds_paragraph_components module provides Paragraph bundles for accordion, alert, cards, columns, modal, process list, step indicator, and summary box. When a component maps to a paragraph bundle, the agent can tell the developer to install the module rather than building from scratch. We created this module, along with USWDS CKEditor Integration and USWDS Layout Builder Configuration, while building custom UI components for pandemicoversight.gov (PRAC). The three modules were released as Drupal contrib projects so other government teams could use them.

Plotly.js

The plotly_js module provides a field type for charts (bar, line, pie, scatter) using Plotly.js. The registry recommends this for data visualizations instead of USWDS's limited chart patterns.

The goal is straightforward: make it easier for AI tools and Drupal developers to move from "use this USWDS component" to "here is exactly how to build it in Drupal."

Drupal USWDS AI Components

Theme Override Guidance

One of the hardest calls in Drupal theming is where a customization belongs: USWDS Sass setting? Scoped CSS? Custom property? Preprocess function? Twig override? JavaScript?

The registry includes a theme override guide with a decision tree so the agent puts it in the right layer instead of dumping everything into Twig.

How the Pieces Connect

The three projects in this series form a stack:

  • Drupal Dev MCP — Drupal API documentation in a vector database. The agent knows what hooks, services, and APIs exist.
  • USWDS AI Components — USWDS component knowledge with faceted search. The agent knows which component to use and how to adapt it.
  • Drupal USWDS AI Components (this project) : The bridge. The agent knows how to implement the USWDS component in Drupal: which module, which paragraph, which template.

Together, they give an AI coding agent enough context to build a government-compliant Drupal site without hallucinating APIs, inventing components, or placing code in the wrong layer.

Technical Foundation

Like the design registry, this extends the AI Component Registry Spec as a git submodule. The spec provides the retrieval protocol, index generator, and templates. This project provides the Drupal content. Same three-file retrieval: facets file, lean discovery index, and per-component files fetched on demand.

The project is MIT licensed. USWDS is in the public domain. The referenced Drupal modules are GPL-2.0. The full registry is available at github.com/ednark/drupal-uswds-ai-components. We'd like feedback from Drupal developers, USWDS practitioners, and anyone working on AI-assisted implementation workflows. If that's you, get in touch.