Our original UI for branding forms left a lot to be desired. The options were a header image and either a background color or image. That’s it. If a campaign or organization wanted to brand their contribution form any further, they had to know how to write CSS or hire a consultant to do so. This created a big barrier of entry for smaller groups.

On top of this, the custom CSS that was written started to become a huge headache for our internal engineering teams. The markup for these contribution forms was not originally written in a way that would be conducive to outside styling. And so, those who wrote custom CSS would grab any selector they could to make their styles work. It got to a point where we literally could not change an H2 tag to an H3 tag without breaking the custom styles of multiple high-profile forms. Our engineering teams were writing worse and worse markup and CSS in order to release features without breaking custom CSS.

And so we set out on our "Better Brandings" journey, with the goal of making custom branded contribution forms accessible to campaigns and organizations of all sizes, without anyone ever needing to write a line of custom CSS.

a collection of custom forms that changed text and button styles

In order to determine what styling options we should make available to our users, I decided to start by first taking an inventory of common patterns being created with custom CSS. I worked with our internal accounts team, which we call Outreach, to get a list of some of our top raising forms, as well as forms that have custom styles that they see often (or maybe just thought were really cool!)

some early sketches/notes-to-self about common customization patterns

I studied these forms, while also gathering inspiration from other donation platforms and websites, and came up with some options that I thought we should make available via our new-and-improved customization UI. If the goal was to greatly reduce the need or desire for groups to have to write their own custom CSS, I wanted to make sure that the things they were already doing would be possible via the UI.

a collection of custom forms that use what I call "color blocking"

One common pattern was something I referred to as "color blocking." This is basically just setting a different background color to different parts of the form. For example, I often saw contribution forms where there was a full-width header with a different background color, or the portion of the page with the actual donation form had a different color, etc. I created maps of the different sections I often saw getting different color treatments, and tweaked them until all the common patterns would be achievable.

a screenshot of a form upon which I highlighted what I considered to be the main sections that should be styleable

the "key" to my content map

the various layout options I wanted to make available, and how the sections would shift accordingly

I played with these section maps in Code Pen, making quick, fun brandings to test common patterns, as well as invent some new possibilities!

I compiled a list of all the customization options I thought we should make available and together with my Engineering Manager and Product Manager, we shared our plans out with other teams. We checked with Outreach to make sure they thought candidates and organizations would be happy with the available options. We checked with legal and marketing to double check what shouldn’t be customizable. For example, we asked questions about how prominent should our own brand be, and whether or not groups should be allowed to change the styles of contribution rules.

After deciding what should be customizable, it was time to figure out the UI for actually doing the customizing.

the UI for editing button styles

We wanted to consider the needs of multiple types of candidates and organizations fundraising with ActBlue. Some are quite large and might have dozens of saved custom form brandings. Others are small and may only have 1. What does the customization experience look like for super vs. casual users?

the user flow for editing an existing branding

We decided to provide the ability to create either one-off "brandings," meaning you just wanted to quickly edit the form you’re looking at, while also adding the ability to save these "brandings" for future use on other contribution forms. I had just designed another similar experience involving settings that can be created and reused on other forms, so I followed my own patterns I had created for consistency.I also worked closely with the engineer who was working on the backend for this feature, as the experience we ultimately settled on required changes to how we modeled saved brandings on the backend.

the user flow for creating a new branding

I also collaborated closely with this engineer to figure out exactly how we would go from customization UI to customized form. We knew that we needed a live, side-by-side experience where a user could change customization settings on one side and see those changes instantly applied to the form on the other side. Our codebase was already set up to do this as far as content went, so that users could change text, goal thermometers, and other things like that. But we weren’t set up to do this from a style perspective.

Our forms were currently being styled with a mix of legacy, old-school SASS, and some newer CSS-modules. Styled-components, a way to style components using JS, was the new hotness at the time. I had been eager to try it out for a while, but didn’t want to introduct a new way to apply styles without a reason. Styled-components makes it so easy to apply CSS to React components based on that component’s props, and since we would need to be able to quickly change lots of styles based on a user’s selections, we had found ourselves with the perfect use case for styled-components.

a fun feature we implemented post-launch to celebrate Pride!

I did a bit of research into Styled-components, comparing it with competitors such as Emotion. I test-drove it, and presented to the team the benefits that it offered us, why it made sense to introduce it for this project, and provided examples of how to work with Styled-components. We decided to give it a go.

We planned to offer lots of options for customizing forms, but not ever option had to be decided on by the user. Heck, they didn’t have to style anything if they didn’t want to. There were and continue to be plenty of contribution forms on ActBlue that use our "default" branding. The other engineer and I discussed how to handle combining our default branding with a user’s custom options.

Styled-components takes a theme, which is basically a javascript object with a bunch of variables set, similar to how you would set variables in SASS. I created a branding object within the main theme object, and then objects within branding for each section of the form that would be customizable. I already had my list of every customization option from the design process, so I created a key/value pair for every single option, and set the value to what our default branding would be.

This is where the other engineer came in. She wrote some code that essentially merged whatever branding values the user set via the UI with our default branding values. This merged branding object is what was passed in as the Styled-components theme, and so all of our styles could simply be written as props.theme.branding.value which kept our code looking SUPER clean and legible. Years later, I’m still in love with how all of this works!

I wanted to be sensitive to the fact that even though the customization features we were planning to offer were extensive, they would not cover all use cases. Afterall, I personally love to write CSS and developed this love back in 2008 when I picked it up in order to hack the styles of my MySpace page (am I showing my age?) I knew that no matter what, some groups would still want to write custom CSS. So, we wanted to still allow custom CSS, but didn’t want to fall back into the situation where we couldn’t develop on our own forms without breaking custom CSS and making groups upset.

guidance about custom CSS

My team and I talked with Outreach, and we were given the green light for adding a warning to the UI where custom CSS was to be added, saying that it should be added at their own risk, and that we were not responsible for custom CSS breaking. But because I have experience adding custom styles to platforms like Squarespace, Wordpress, and yes, MySpace, I wanted to give a little present to our users. I started adding very noticeable classes to the HTML tags, that started with CSTM- and ending in a human-readable, descriptive label. We added to our warning that users should try to use these classes as much as possible, and that these were much more likely to remain supported.

Once everything was built out and ready to go, how we released brandings was a huge project in itself. A lot of planning went into the release, and our Engineering Manager and Product Manager played huge roles here. They were able to negotiate expectations with the Outreach team. Remember how one of the main problems was groups getting upset if we broke their custom CSS? Well, we certainly couldn’t just up and break the visual presentation of everybody’s form. So we came up with a plan.

First, we (okay, the other engineer and Engineering Manager) copied the production database with all of the latest brandings to a staging environment. We deployed the new branding experience to the staging environment, as well. Outreach provided us with a list of high-profile groups and their forms that used custom CSS. Our entire team spent a couple weeks recreating these custom brandings using our new brandings UI on the staging environment, filling in with new custom CSS (using the CSTM- tags I provided) where necessary. We also made an announcement to the rest of users announcing the upcoming changes, and giving them time to recreate their own form brandings using the new UI on the staging environment.

warnings we surfaced pre-launch

Essentially, by the time deploy day came along, we had a database with everybody’s new customized forms ready to go! To deploy, the engineers merged staging’s branding table with production’s, deployed the new code itself, and... everything worked. All the work and planning paid off.

Brandings ended up being a hugely successful release. We enabled candidates and organizations to create unique, fully customized forms despite not having the resources to devote to writing custom CSS. We solved a huge internal problem of not being able to write clean, sustainable, or accessible code over the fear of breaking custom CSS. Seriously, two-years later, hardly a peep about brandings getting in the way of feature development. Our users have widely adopted the feature, and a recent survey at the end of 2020 showed that many of our users love "Better Brandings."