CivicTheme is a design system and component library for GovCMS and Drupal. In a typical implementation, you run the distributed CivicTheme code as a base theme and layer a project-specific sub-theme on top, where the real site-level templates, components, and styling live. Upgrades therefore juggle two moving parts: the CivicTheme library itself and the sub-theme that implements the design system for a particular site.
Those upgrades can quickly become slow and risky, especially once you layer in custom components and client-specific styling.
We built the "CivicTheme Upgrade Lab" to change that equation. It's a documentation-first framework that works with any AI coding assistant and treats every upgrade as both a delivery task and a learning asset. In our implementation we paired Codex with GPT-5.1. The lab lives in a dedicated repository and captures the upgrade scripts, AI prompts, and customisation records for each site, turning what's typically tribal knowledge into shareable, version-controlled intelligence.
In this insight we walk through:
- how the framework works,
- how we used it to upgrade a real client site from CivicTheme 1.10.0 → 1.11.0 → 1.12.0 → 1.12.1, and
- why this approach cuts upgrade time while improving documentation for the next release.
Why CivicTheme upgrades are slower than they look
On paper, CivicTheme upgrades look like "just" theme and dependency bumps. In practice, CivicTheme is a design library with a base theme plus a project-specific sub-theme where most of the customisation sleeve lives. Most production sites carry:
- custom components layered on top of CivicTheme,
- tweaks to templates, view modes, and preprocess hooks, and
- hand-written CSS to match agency or department branding.
As CivicTheme evolves, new releases naturally change markup, CSS variables, or behaviours. When a site carries customisations, those changes can sometimes require adjustments to keep everything aligned. The result?
- 8–16 hours of manual work per upgrade,
- repeated rediscovery of "how this component was customised last time", and
- documentation that lags behind the code or never gets written at all.
In many teams, the details of how each component was customised live mostly in the head of the engineer who ran the last upgrade. When a different engineer takes on the next release, they must reverse-engineer those decisions. That slows the work, increases the chance that customisations are missed, and pushes more regressions into QA where they're harder and more expensive to fix. A documentation-first approach makes those decisions explicit so the next person doesn't have to rediscover them from scratch.
The CivicTheme Upgrade Lab is our answer: a repeatable, AI-assisted workflow that gets faster the second time you run it.
The CivicTheme Upgrade Lab in three ideas
The lab is a small repository (for example, our civictheme-upgrade-lab project) plus a set of conventions. Three core ideas drive it:
1. Everything lives in Git
Each CivicTheme upgrade for a client gets its own workspace containing:
- a snapshot of the site's current CivicTheme version,
- scripts and configuration for the automated upgrade tool,
- a registry of custom components and theme overrides, and
- a running log of "customisation records" that explain what changed and why.
Instead of relying on memory, we push every decision into version control where it can be audited, reused, and refined. Knowledge becomes infrastructure.
2. AI-native from the start
The lab assumes an AI coding assistant is available from day one. In our implementation we use Codex with GPT-5.1 as the engine behind the scenes.
The assistant:
- reads CivicTheme CHANGELOGs and upgrade notes,
- runs the automated CivicTheme upgrade tool,
- proposes code changes to bring custom components forward, and
- drafts documentation for each customisation and regression fix.
We have deliberately tested the same CivicTheme upgrade flows across different tools and models. Using the identical starting prompt in Cursor with a GPT-5.1 High configuration left our 1.10.0 → 1.11.0 upgrade in a significantly broken state, with major regressions. By contrast, the Opus 4.5 "thinking" model completed the same jump end to end on the first attempt, carrying all sub-theme customisations forward so that the upgraded site was effectively indistinguishable from the original.
Humans stay firmly in the loop. Engineers review diffs, decide what to merge, and run manual tests on top of automated checks. AI accelerates the work; it doesn't replace engineering judgement. Think of it as a turbocharger for the mechanical parts of the upgrade whilst preserving human oversight for the critical decisions.
3. Documentation is a deliverable
The framework treats documentation as a first-class output, not an afterthought:
- For every regression or manual tweak, we create a customisation record in the lab.
- Each record describes the component, the CivicTheme versions involved, symptoms, root cause, and the final patch.
- The AI assistant helps draft these records, but engineers own the final wording.
By the time an upgrade is complete, we deliver both a working site and a detailed map of how it differs from upstream CivicTheme. The next upgrade starts from that map instead of a blank page. This is the compounding advantage: each upgrade builds on the intelligence from the last.
One important detail: the lab isn't a single generic "upgrade CivicTheme to the latest version" tool. Instead, we bundle each version bump into the lab repository as its own configuration and notes (for example, 1.10.0 to 1.11.0 and 1.11.0 to 1.12.0). Some of that content naturally duplicates what you see in CivicTheme release notes, but the duplication lives in separate files that act as playbooks. Those playbooks describe both implementation steps and verification steps, so the AI agent has an explicit task list to follow and a checklist it can use to validate when its work is complete.
The CivicTheme Upgrade Lab repository is public, and you're welcome to try it on your own CivicTheme projects. The README walks through how to install the lab into an existing Drupal codebase and links to a ready-made starting prompt for AI assistants: copy and paste it rather than writing your own from scratch (though you're welcome to adapt it). Clone the lab, follow the version bump playbooks that match your current release, and let us know how it behaves by submitting issues or ideas directly in the GitHub project. Feedback from real-world upgrades will shape how we evolve the task lists, documentation patterns, and AI prompts over time.
A real upgrade: 1.10.0 → 1.12.1 in four hours
To test the framework, we pointed the CivicTheme Upgrade Lab at a real client site running CivicTheme 1.10.0. The site carried around five custom components built on top of CivicTheme, enough complexity to be representative without being exotic.
Historically, a manual upgrade for a site like this would demand 8–16 hours, spread across upgrading the theme, reconciling custom code, and retesting the front end.
With the lab, the entire exercise (from 1.10.0 to 1.12.1) took four hours, covering both the CivicTheme library updates and the sub-theme adjustments:
- ~1 hour on the actual version bumps and code changes.
- ~3 hours on identifying customisations, hunting regressions, and documenting everything properly.
Step 1: Automated upgrade to CivicTheme 1.11.0
We started by wiring the project into the lab repository and configuring the automated CivicTheme upgrade tool to target 1.11.0. The tool updated the CivicTheme base library first, then proposed corresponding changes in the project sub-theme so templates and styles matched the new framework behaviour.
Using Codex, we:
- supplied the repository, lab configuration, and an Anthropic API key,
- asked GPT-5.1 to run the CivicTheme upgrade tool for the jump from 1.10.0 to 1.11.0, and
- let the assistant propose the necessary code changes as a series of diffs in the same working branch.
The human focus shifted to review and testing, not manually editing every template. The coding assistant handled the mechanical parts: running the tool, adjusting the sub-theme, and wiring in the new CivicTheme version.
Step 2: Manual testing and custom component triage
Once the site was on 1.11.0, we ran through our usual manual regression pass:
- cross-browser checks on key templates,
- targeted journeys through pages that rely heavily on the five custom components, and
- accessibility and layout checks on common content types.
We did see regressions: a couple of custom components rendered incorrectly because our overrides needed updating to align with the markup and CSS changes between 1.10.0 and 1.11.0.
Here the CivicTheme Upgrade Lab and GPT-5.1 worked in tandem:
- We asked Codex to compare the upstream CivicTheme templates with our custom overrides and highlight where adjustments were needed.
- The assistant proposed patches to align our components with the new markup and styling whilst preserving the custom behaviour.
- For each fix, it drafted a customisation record describing the issue, the analysis, and the patch.
Engineers then reviewed the patches, made any necessary adjustments, and merged them. The result: the site was clean on 1.11.0, and we'd documented exactly how our custom components diverged from upstream CivicTheme.
Step 3: Incremental upgrades to 1.12.0 and 1.12.1
With 1.11.0 stable, we repeated the process for 1.12.0 and 1.12.1.
- Codex updated the tool configuration to target 1.12.0, ran the upgrade, and surfaced the resulting code changes.
- During manual testing we noticed minor stylesheet regressions: small visual differences and spacing issues where our custom styles needed adjusting for the new release.
- GPT-5.1 again helped by isolating the changes in CivicTheme's CSS and suggesting minimal patches to our overrides.
Each of these fixes went into the customisation documentation for the site, linked to the specific version jump (1.11.0 → 1.12.0).
Finally, the step from 1.12.0 to 1.12.1 was uneventful. Thanks to the groundwork in earlier steps and the documentation already in the lab, the last increment was essentially a verification exercise. The automated tool updated CivicTheme to 1.12.1; we reviewed the diff, reran tests, and confirmed no new regressions. Smooth sailing.
Time breakdown: where the four hours went
Across all three increments (1.10.0 → 1.11.0 → 1.12.0 → 1.12.1), our time broke down like this:
-
~1 hour: actual upgrade work
- Running the CivicTheme upgrade tool through Codex for 1.11.0 upgrade.
- Letting the AI assistant to investigate, document and reapply customisations and confirm that customisations still applied cleanly after each bump, instead of doing that comparison manually.
- Executing automated and visual regression tests.
- Reviewing and applying AI agent-documented customisations and re-running automated checks.
-
~3 hours: understanding and documenting customisations
- The bulk of this time (around two to two and a half hours) was invested during the first bump from 1.10.0 to 1.11.0 whilst the AI ssistant identified (and we reviewed) how the five custom components behaved before and after the upgrade and AI assistant capturing those differences.
- The remaining time covered minor regressions in the 1.11.0 to 1.12.0 and 1.12.0 to 1.12.1 steps, plus instructing the AI coding assistant to log each fix and decision as a customisation record.
This is the key point: the majority of the time was spent turning implicit knowledge into explicit documentation. The site didn't just get upgraded; it received a durable reference for every meaningful deviation from stock CivicTheme, especially in that first major increment.
Why this framework saves time now and later
Even on this first run, the CivicTheme Upgrade Lab delivered a clear win:
- A task that traditionally takes 8–16 hours was completed in four.
- Most of the "extra" time went into documentation, which pays dividends on the very next upgrade.
But the bigger advantage compounds over time:
- Future upgrades are incremental. To support a new CivicTheme release, we introduce the new version into the lab tool, let Codex run the automated upgrade, and focus on review and testing. The customisation records tell us exactly where to look.
- Risk drops. Because the framework assumes regression hunting and documentation as part of the work, we're far less likely to be caught off guard when a future release requires adjustments to our customisations.
- Knowledge is portable. If a new team member joins the project, or if the client's internal team takes over, they can see why each custom component exists and how it's survived past upgrades, instead of having to rediscover that history by reading code and waiting for QA to surface regressions.
AI doesn't remove the need for careful engineering, but it does remove a large amount of mechanical, repetitive work. The lab ensures that the time we save gets reinvested in better documentation and testing, not in simply shipping faster and hoping nothing breaks.
What this means for your next CivicTheme upgrade
If you're running CivicTheme on GovCMS or Drupal, your next upgrade doesn't have to be a long, manual exercise:
- We can onboard your site into the CivicTheme Upgrade Lab.
- Codex and GPT-5.1 handle the repetitive upgrade and diff analysis work.
- Engineers concentrate on regression testing, accessibility, and making informed decisions about customisations.
- You receive an upgraded site plus a living catalogue of your CivicTheme customisations.
For this client, the first run through the lab delivered a clean upgrade from 1.10.0 to 1.12.1 in four hours, including documentation. Our expectation is that the next CivicTheme release will be even faster to adopt: we'll add the new version to the lab's toolchain, run the automated upgrade, and use the existing customisation records as our guide. The framework gets faster with every release.
If you'd like your next CivicTheme upgrade to feel less like a one-off project and more like a predictable, documented process, we'd be happy to walk you through the CivicTheme Upgrade Lab in detail.
