How a design system connects to Drupal, and when teams need it
Connecting a design system to Drupal means turning the system's components, design tokens and markup patterns into Drupal theme and rendering code, so that the same button, card or form renders consistently on every site that uses it. The work sits between the design team's source of truth (usually a component library, a token file and its documentation) and Drupal's theme layer, where templates, CSS and JavaScript are assembled into pages, Layout Builder sections and content entities. Teams usually need this work when more than one Drupal site must share a brand, when a design system already exists but was built for a different framework, or when a partner is taking over front-end delivery and needs a clear contract for what the components are and who may change them.
Drupal is licensed under GPL-2.0-or-later and has no paid edition, so the integration layer is custom work that your organization owns. Nothing in the core or in a commercial license will map your tokens to Drupal for you. Before quoting or starting, confirm three things in writing: which design system version is the baseline, which Drupal major version each site runs or will run (Drupal 11 is the current major version, and Drupal 10 reaches end of life on December 9, 2026), and whether every site is self-hosted in infrastructure you control. A team that cannot answer the first question usually discovers mid-project that the component library and the Drupal theme have drifted apart, which turns a bounded integration into an open-ended rebuild.
Integration options for a design system in Drupal
This table compares four ways to bring a design system into Drupal: single-directory components in a custom theme, a Starterkit-based theme, a shared Twig component library, and a headless front end. Read each row as a trade-off: the option that fits your team, the coupling it creates, and the upgrade effort it leaves behind. The main takeaway is that the cheapest integration today is not always the cheapest across several Drupal major versions.
| Option | When it fits | What it couples | Upgrade cost |
|---|---|---|---|
| Single-directory components in a custom theme | One Drupal site or a small estate where the same team owns the theme, components and design tokens | Component markup, CSS and JavaScript to the theme and to Drupal's component rendering in core | Moderate: component files stay in the theme, so upgrades mainly test template and library changes |
| Starterkit-based custom theme | A new theme that must avoid inheriting from Olivero or Classy, and that the team will maintain for years | Theme structure and build tooling to the Starterkit output, with the design system layered on top | Low to moderate: the theme is owned code, but the team must still review the design system's own dependencies at each upgrade |
| Twig component library with a shared package | Several sites that must share one versioned set of templates and styles through a package | Package versioning, Twig template contracts and the release cadence of the shared library | Moderate to high: every breaking change in the library needs coordinated updates across all consuming sites |
| Headless front end consuming the system | Content that must appear in several channels, or teams that already run a separate front-end stack | Drupal's content API, JSON:API customization, previews and a second deployment pipeline | High: two codebases, two release trains and an API contract to keep stable through Drupal 11 and Drupal 12 planning |
| Token and markup sync | Any option above, since tokens and markup drift in every model | A shared source of design tokens that must be built into CSS and checked against component output | Ongoing: needs an owner and a review step on every design system release |
How to build the integration in sequence
The sequence turns a design system that already exists into Drupal components, theme code and governed releases, with a check at each stage so that drift between the design system and the rendered site is caught before it reaches production. Each step produces an artifact the next step depends on.
Audit tokens and components before writing code
The design system owner and a Drupal lead inventory every token category (color, spacing, typography, radius, elevation, motion), every component, its variants, states and slots, and the markup each one currently emits. The team also records which components already exist in Drupal contributed or core projects and which need to be built. The output is a shared inventory with a decision for each item: reuse, adapt or build. Done means the owner has signed off the inventory, and the list of components that have no clear Drupal equivalent is short enough to scope. Ask the design system team which parts are stable and which are still changing, because unstable parts should not be built into Drupal first.
Choose the Drupal rendering targets
Decide which components render through Twig templates, which become Single-Directory Components, and which are exposed to Layout Builder or Drupal Canvas for editors to place. Twig suits fixed page regions and field output. Single-Directory Components suit reusable units with props and slots that several rendering paths need. Layout Builder and Canvas suit components editors arrange on pages, and each has its own limits on what editors can configure. The output is a rendering matrix listing each component and its targets. Check it with the editorial team by walking through two or three real page types and confirming that editors can build them without developer help.
Generate a custom theme with Starterkit
Create the base theme with the core Starterkit generator rather than subtheming Olivero or another core theme. Subthemes inherit template and library decisions that the design system then has to override, which creates upgrade debt. Starterkit gives the team a theme it owns, with the design system's build tooling placed in the theme repository. The developer runs the generator, sets the theme name and libraries, and commits the result under version control. Done means the empty theme installs on a clean Drupal site, renders the default regions and passes the coding standards checks your team uses. Confirm the Starterkit version matches the Drupal version your project targets before you start.
Map tokens to CSS custom properties
Convert the design tokens into CSS custom properties in a single source file that the theme loads, and generate them from the design system's token source rather than typing values by hand. Name the properties consistently, keep semantic tokens (for example, a primary action color) separate from raw palette values, and document any token that a site is allowed to override. The output is a generated stylesheet and a short mapping document. Check it with a rendering comparison: render the same component in the design system's own documentation and in Drupal, at the same viewport, and review differences pixel by pixel or with a visual diff tool. Mismatches usually point to a missing token or a hard-coded value in a template.
Build the component library with visual and functional tests
Implement each component as a Single-Directory Component or Twig template with its props, slots and variants, then add tests at two levels. Visual tests capture each component state and compare it against a baseline. Functional tests check behavior such as menus, dialogs and forms, and the rendered markup they depend on. Run an accessibility review on every component with keyboard-only navigation, a screen reader pass on interactive parts, and an automated scanner. The output is a component catalog that engineers and editors can browse, plus a passing test suite in CI. Done means every component in the catalog has baseline images, passes functional tests and has a recorded accessibility review with open issues assigned.
Set the release and versioning process
Define how changes to the design system reach Drupal sites. Decide the versioning rule for breaking changes to props, slots and tokens, who approves a release, how a site opts in to a new version, and how a site can pin the version it runs. Record the process in the repository. Plan the review against Drupal's own release cadence: bugfix releases arrive on the first Wednesday of each month and security releases on the third Wednesday, so the theme and component library need a routine for checking compatibility with each update. The output is a written release policy and a changelog template. Check it by shipping a test release to one pilot site and confirming that the site upgrades and rolls back cleanly.
Roll out across sites and keep it governed
Install the shared theme on the first production site, then extend it to others in the estate using the release policy. Each site consumes the same component library version and records any local overrides in a register that the platform team reviews during each release. Governance covers who can request a new component, how overrides are reviewed, and when a site must upgrade. The output is an operating model with named owners and a pilot site that has been running the release process. Done means a second site has received a release through the process without manual edits to the theme, and the override register is reviewed at every release.
How tokens and markup stay in sync across sites
The sync problem starts when a design system changes its tokens or component markup and nobody owns the mapping into Drupal. A color variable is renamed, a button gains a new state, or a card loses a wrapper element, and each Drupal site's Twig templates and theme CSS quietly keep the old version. After a few releases, every site has a different idea of what the brand looks like, and the design system team can no longer tell which sites are affected by a change. The fix is organizational as much as technical: name one owner for the mapping between design tokens and Drupal templates, and make that owner accountable for every release that touches either side.
The pattern that holds up across many sites has three parts. First, the design system's components are published as a versioned component package that each site's theme consumes at a pinned version, so a site upgrades on purpose rather than picking up changes by accident. Second, a token build step converts the design system's token source into the files the theme reads, such as a generated stylesheet or a PHP-readable mapping, so color, spacing and typography values are never copied by hand. Third, automated checks render the Drupal components and compare their markup and class names with the package's reference output, failing the build when they diverge. The exact tooling depends on how the design system stores its tokens and components, including the token file format, the build tool and whether components are shipped as Single-Directory Components or static markup. Confirm those details with the design system owners before choosing any tool, because the build step and the checks must read the same source.
Security and operational risks in shared component libraries
A shared component library changes the risk profile of every Drupal site that consumes it. The risks below share one cause: code and markup that many sites depend on are maintained in one place, so a flaw, a dependency or a configuration choice spreads wherever the library is installed.
Third-party frontend dependencies
A design system usually pulls in npm packages for icons, carousels, date pickers or accessibility helpers. Each of those packages ships to every Drupal site that loads the library, so their licenses, bundle size and maintenance status become shared obligations. Ask for a list of runtime dependencies, check which ones load on every page, and decide who owns upgrades when a package is abandoned.
Escaping and XSS in components
Components that render editor-supplied text, links or embedded markup are a common route for cross-site scripting. Twig auto-escaping protects plain fields, but a component that accepts raw HTML, or passes attributes through without filtering, can reintroduce the flaw in every site at once. Review each prop that reaches the DOM unescaped, and test components with hostile input from the rich text editor.
Content Security Policy conflicts
Sites that adopt a strict Content Security Policy often find that a library's inline scripts or styles are blocked. Fixing this per site leads to relaxed policies that weaken protection everywhere. Agree on the policy once, move inline code into external files or nonces, and test each component under the production header set before a release goes to any site.
Supply chain controls for npm packages
Build tooling and frontend packages can be compromised through typosquatted names, malicious releases or stolen maintainer credentials. Lock files, reviewed upgrade pull requests, private registry mirrors and checksum verification reduce that exposure. Confirm who can publish to the library's package scope, whether builds run in a clean environment, and how a bad release is revoked across sites.
Cost of patching shared libraries
A fix to a shared library must reach every consuming site, and each site may pin a different version or carry local overrides. Patch effort grows with the number of sites, the number of overrides and the gap between versions. Ask how releases are versioned, how sites declare the library version they run, and how a security fix is rolled out and verified on each site.
Advisory coverage for internal code
The Drupal Security Team handles vulnerabilities in Drupal core and contributed projects, and publishes advisories for those projects. It does not cover a client's own component library, so no advisory will announce a flaw in it. Assign an internal owner to monitor dependency advisories, run scheduled scans, and publish your own notices to the teams that run each site.
Questions teams ask before connecting a design system to Drupal
What does it cost to connect a design system to Drupal?
The cost depends on how much of the design system must be rebuilt as Drupal components, how many sites consume it, and how much governance you need around it. Most of the spend is skilled front-end and Drupal engineering time, plus design review and testing. Ask for a written scope that lists the components in the first phase, the token format, the Drupal theme and component approach, the sites in scope, and the test environments. Each of these changes the effort directly. No price is given here because a quote follows from the written scope, and DeployOpen does not publish a price list.
What drives the effort when integrating a design system with Drupal?
Four factors usually move the effort most:
- How closely the existing components match Drupal's rendering model, including Twig templates, field output and Layout Builder or Canvas placement.
- How many components need props, slots or variants that editors can set without code.
- Whether tokens are exported from a single source and consumed by both the design system and the Drupal theme.
- How many sites share the library, since each site adds regression testing and release coordination.
Ask the vendor or delivery team to inventory components against these four factors before agreeing a timeline.
How long does a design system integration take?
The duration varies with the size of the component inventory, the number of sites, and how stable the design system already is. A library with a documented token set and tested components integrates faster than one that exists only in a design file. Timing also depends on your approval cycle and on how quickly your team can review rendered pages in a test environment. Ask for a phased plan in the written scope, with milestones for the first component set, the first live site, and each later site. Treat any single number without that breakdown as a guess.
What does our team need to provide before the work starts?
Three inputs make the largest difference:
- A named owner for the design system who can approve token and component changes.
- A component inventory with current markup, accessibility notes, and known variants or deprecated patterns.
- A test environment that mirrors production hosting, with a Drupal install and access for reviewers.
You will also need someone who can decide how editors use components in content, since that choice shapes the component API. Confirm each item in the written scope so that waiting on inputs does not extend the timeline without notice.
Can our in-house team connect the design system to Drupal without a partner?
Yes, a capable in-house team can do this, provided it has Drupal theming experience, front-end component skills, and time for review and testing. A partner is useful when the team lacks recent Drupal theming experience, when the work must be finished alongside other launches, or when a second pair of eyes is needed on governance and upgrade safety. Compare the two options using the same written scope: the component list, the test coverage expected, the upgrade approach, and who maintains the library after launch.
How does the design system integration affect an upgrade to Drupal 12?
Components that depend on core theme internals or on deprecated Twig and JavaScript patterns carry the most upgrade risk. Components built with clear props, documented template variables, and automated tests are easier to carry forward. Drupal 12 is scheduled for the week of December 7, 2026, and the Drupal core release schedule states that Drupal 10 reaches end of life on December 9, 2026. Ask your delivery partner to show how each component is tested against the next core version and which deprecation checks run in continuous integration before you plan the upgrade window.
What recurs after a design system integration goes live?
Recurring work includes updating the library when the design system changes, keeping tokens and markup in sync across sites, reviewing component changes, running regression tests, and applying Drupal core and contributed module updates. Core bugfix releases arrive on the first Wednesday of each month, and security releases on the third Wednesday, so release planning must allow for both. Ask whether the scope includes ongoing support or a retainer, who approves changes to shared components, and how a change to one site is tested before it reaches the others.
Governing changes across many sites
The central team should own the shared component library and be the only group that merges changes to it. Site teams propose changes as pull requests against the library, and the central team reviews each one for markup contract changes, token renames, accessibility impact and effects on every consuming site. Name reviewers and a backup for each component area in writing, and agree which changes need a second reviewer, typically anything that alters a prop, slot, Twig variable or token name. Code review and automated testing practices from Drupal projects apply to this theme code as well: the same review checklist, Drupal coding standards checks and browser tests on critical components should gate every merge, so a library change cannot reach a site without passing the same checks as site code.
Sites should pin the library to a specific version through Composer rather than tracking a development branch, so each site upgrades on its own schedule after testing. Record the pinned version of the component library and theme in each site's repository, and make the upgrade a reviewed change that runs visual regression and functional tests on that site. Confirm with your team how the library is published (a private Composer package, a monorepo path or a git tag) and whether your release tooling supports the version ranges you want. Keep a changelog that lists every component whose markup, props or tokens changed, because that list is what site owners use to plan their work.
Breaking changes need a deprecation window. Keep the old component or token working for a stated number of releases while the new one ships alongside it, mark the old one as deprecated in the Twig template or component documentation, and log a warning or a Storybook note so site teams see it in their own review. Agree the length of the window with the site owners before you publish the change, and confirm that your own release policy and the Drupal core release cadence allow for it. Remove the deprecated code only in a major library release, and make the removal a checklist item that each site must clear before it pins the new version.
How to verify the integration before rollout
This sequence turns the design system integration into measurable acceptance criteria, then proves the components render, read and behave correctly in each Drupal site before any site receives the change. The client signs off on these checks as part of the written scope, so the result is a documented release decision rather than a visual judgment.
Agree the acceptance criteria in writing
Before any test is written, the client and DeployOpen list the components in scope, the design system version they must match, the accessibility target the design system states for each component, and the browsers and Drupal versions that must be supported. These items go into the written scope as the acceptance criteria for the integration. The step is done when each criterion has a named owner and a pass or fail definition that the client has approved.
Run component-level tests in isolation
Each Single-Directory Component or Twig component is tested outside a full site, using the test harness the design system already provides or one set up for the Drupal theme. Tests cover required props, default values, slot handling, empty states and token-driven styles such as color and spacing. The step closes when the component suite passes in continuous integration on every branch that changes a component or a token file.
Capture rendering snapshots in each Drupal site
Components are rendered inside each Drupal site that will consume them, using real Layout Builder, Canvas or Twig placements, and the markup and screenshots are stored as baselines. Comparing against these baselines catches cases where a site's own theme overrides, module markup or field configuration changes the output. The step is complete when every site has a baseline, and each change to the component library produces a reviewed diff rather than an unreviewed visual shift.
Check accessibility against the stated targets
Automated accessibility scans run against the rendered snapshots, and the results are compared with the accessibility targets the design system documents for each component. Automated scans cover only part of accessibility, so keyboard navigation, focus order, heading structure and screen reader labels are checked manually for the components the client marks as high risk. The step closes when every failing item is fixed in the component or documented as an agreed exception with an owner.
Verify behavior across the agreed browsers
Interactive components such as navigation, accordions, dialogs and forms are run through browser tests in the browser and device combinations listed in the acceptance criteria. The tests confirm that JavaScript behavior, layout breakpoints and form submission match the component specification on each combination. The step is done when the browser suite passes and any differences from the specification are logged as defects with a decision on whether they block rollout.
Stage the rollout on one site first
The integration is deployed to a single Drupal site chosen for representative content and traffic, in a staging environment that mirrors production configuration. The client's editors and the owner of that site review real pages, content types and editorial workflows against the baselines and the acceptance criteria. The step is complete when the client signs off the staged site in writing, and any defects found are fixed and retested before the next step.
Roll out to remaining sites and monitor
After sign-off, the same release is deployed to the remaining sites in an order the client sets, with each site's snapshots and accessibility checks rerun against its own baseline. Errors, layout regressions and editor reports are tracked during an observation period the client agrees in advance. The sequence closes when every site passes its checks and the baselines, test results and sign-off records are handed over as part of the project documentation.
What your team provides and what DeployOpen delivers
Before work starts, your team needs to provide read and write access to the design system repository, including the token source files, the component library and its build and release pipeline. Name one owner for design tokens and one owner for each component family, because these people decide which values are canonical and which Drupal components are allowed to diverge from them. You also need working Drupal environments (development, staging and production-like) inside your own infrastructure, with a theme deployment path that your team can reproduce. Finally, name the decision makers for governance: who approves a new component, who signs off a breaking token change and who can accept a deviation for a specific site. Confirm each of these in writing during scoping, since missing owners are the most common reason integration stalls.
Under a fixed-scope agreement, DeployOpen's deliverables for this topic typically include a Drupal theme built from the core Starterkit generator, a mapping document that links each design system component to its Twig template, Single-Directory Component or Canvas component, and the token pipeline that generates the theme's CSS custom properties. The scope also covers automated tests for the critical rendering paths, a handover package with component documentation and a runbook for the sync process, and a short walkthrough for the owners you named. The exact list, the number of components in scope and the timeline are agreed in the written scope before any work begins, so ask for the component inventory to be attached to the scope document. Ongoing sync work, new components after handover and multi-site rollouts are usually priced as separate work or a retainer, so confirm that boundary explicitly.
How DeployOpen scopes, builds and supports design system integrations
DeployOpen plans, builds, documents and supports the connection between your design system and Drupal inside your own infrastructure. Engagements are fixed-scope, with the scope, deliverables and timeline agreed in writing before work starts, and ongoing support is available as a retainer.
How we scope
- Inventory the existing design system, its tokens, components and version history before estimating any build work
- Agree which components move into Drupal first, and which stay in the source library for now
- Write down the Drupal versions, theme approach and sites in scope, including multisite estates
- Record governance rules for who approves token and component changes, in the written scope
How we build
- Map each design component to a Drupal theme component with defined props, slots and template variables
- Build a token pipeline that generates theme configuration from the source tokens rather than copying values by hand
- Add automated tests for component rendering and visual regressions, run in your CI pipeline
- Review custom code against Drupal coding standards and deprecation checks before each merge
How we hand over
- Deliver a component catalog that documents each component's inputs, usage rules and where it appears
- Document the token sync process, including how to add a token and how a release is published
- Walk your team through the change process, release steps and rollback steps before handover
How we support
- Offer a retainer for ongoing token sync, component fixes and Drupal core and contributed module updates
- Track Drupal bugfix releases, which land on the first Wednesday of each month, and security releases on the third Wednesday
- Plan component updates alongside major Drupal version work, such as the Drupal 12 timeline your team sets
