How to pull it all together
An article suggesting that AI meant this was all possible in 3 hours was the starting point that set me off on this adventure. It gave some useful suggestions, but for our site at least (and, arguably, my levels of perfectionism) 3 hours was wildly over-optimistic.
All in all, even with the help of AI, it took me more like 40 hours’ work to get everything set up and functioning in a way I was happy with.
Audit, planning and structure
The first step was to gather all the raw material. WordPress lets you export all content as XML, which was helpful.
I also went a step further and used SiteSucker to create a static version of the site. This meant that AI had a couple of good, local reference points to assess and to build from.
We already had a full set of bespoke content types in WordPress, so I got the AI agent in Windsurf to set those up.
I then worked through a content type at a time, working with the AI agent in Windsurf to detect and build content components: all of the design and structural elements that are repeated across Contentious content, such as hero sections, borders and screenshot holders.
Tokenisation is also an important part of this new efficient, consistent setup and as I worked through the content I tokenised as much as possible. AI was sometimes less than helpful here: it tended to want to take shortcuts and hardcode values rather than take the more sustainable, efficient path.
Markdown or MDX?
I started off using mostly Markdown for content, and ended up using mostly MDX. For the Contentious site, MDX offered more flexibility, which generally trumped the simplicity of Markdown. And I’m happy editing MDX files. As I migrate more content into Storyblok this choice will become less relevant.
The AI was helpful in turning the exported XML content into Markdown, which made this stage pretty painless.
CSS
I considered using Tailwind CSS but decided that it wasn’t really needed. The combination of design tokens, scoped styles and semantic, readable markup makes it an efficient system already.
There was some wrangling involved in getting all of the CSS to work, and deciding what was genuinely site-wide and what was component-specific. But it was worthwhile wrangling: we now have a CSS system which is light years ahead of the mess of rules and exception-rules that had built up over years.
Colour system
In some areas, such as our colour system, we now have not only a tidier system but a much more powerful one. I made good use of Scale by Hayk and codified our colour palette in a way that’ll be invaluable not just for our website but our products and other outputs too.
Privacy, cookies, analytics
It seemed like a good moment to fully switch away from Google Analytics to Umami, which is a great open source, privacy-focused analytics platform. We’re hosting it on Pikapods, which costs us about $2 a month. This is cheaper than using Umami’s own hosted version and means stats are accessed from a Contentious subdomain. We could have self-hosted it, but $2 a month is well worth it not to have to worry about updates and servers, which Pikapods deal with brilliantly.
That also meant reworking our privacy policy and cookies (or, no-cookies) policies.
The style guide
Halfway through the project, I decided that rather than creating another set of documentation I should rebuild the Contentious style guide as part of the same project, and integrate everything (foundations, words, design and code).
This slowed things down, adding another layer of complexity. But it also made sense to do it now, while all the design, code and structure thinking was fresh in my mind. Abstracting as I went also concentrated the mind on what we needed and what good practice looked like. And having a style guide which publishes to its own subdomain but uses exactly the same code under the hood is a pretty neat solution.
