Since we're working on a complete rebrand, we're also creating all of our CSS from scratch. While we could have reused some of the existing styles, most of them didn't rely on variables, and had multiple implementations of the same things, so this change will allow us to achieve consistency much more effectively.

At the very core of our design system are clearly defined values - a set of base colours, spacers, font sizes, breakpoints, border radii, and box shadows. These are defined at the very top of stylesheets/design. Every value that's used outside of this section should ultimately refer back to these in some fashion, unless it is very specifically and explicitly a hardcoded exception. This will allow us to easily change these values and have them immediately take effect across the entire project, and also give us theming basically for free - all a theme needs to do is change the values of those base colours, and everything else will automatically fall in line.

These values are then used by clearly defined components. Most of the elements on our pages, unless they truly are nothing more than generic containers setting some spacing, should refer back to one of our predefined components. This not only makes it easier to reuse, but it again allows us to make changes globally and consistently without having to find and touch all the specific places a component is used in.

Writing a component in CSS

Most of the components you're going to need should already be defined. If something seems to be missing, check with Maya and/or Jack first - there might be one of our existing components that already covers this use case, or should be adapted to match. If something is truly missing from the component gallery, we’ll want to add it there instead of doing something page-specific. For consistency, here are the principles that were used when writing them so far - and if you see something that you feel does not conform to these in the existing components, please fix it!

• Selectors should match intent, and not be too general, nor too specific. For instance, applying a global style to button should mean that we want want all of our buttons to have that style. This goes both ways - if the style you’re looking to add is in any way specific to a set of circumstances, look for a more specific selector. On the other hand, don't fear exceptions. Yes, something at some point may need to be a button for accessibility or JS reasons while having different styles, but the selector should still be modeled after the design intent.
• Semantic elements > ARIA attributes > pseudo-elements > custom classes. Wherever possible, avoid introducing CSS classes for things that can be represented using native relationships and attributes, especially for children of components. This gives us implicit accessibility as semantic elements, ARIA attributes and DOM structure convey meaning to screen-readers, while classes are invisible to them. It's also more convenient to write, as elements just fall into place rather than having to assign them specific classes, and fewer classes generally means fewer name conflicts. At the same time, don't misuse semantic elements or ARIA attributes just to avoid defining a class. Use them wherever possible within the ARIA spec.
  • Wherever possible, use applicable semantic HTML elements, attributes and nesting to model your styles. Again, don't be afraid of exceptions - if the intent is to have all buttons in a certain context look the same, then write it that way and account for exceptions later. Note: div and span are not semantic elements. You never want to select by them.
  • Where there are no built-in HTML elements or attributes to represent your component, part, or state, try correctly using an ARIA role or attribute.
  • If what you're describing is purely visual like a status icon, consider using a pseudo-class for it rather than requiring the user to put it in their HTML. It will make your component that much easier to reuse.
  • If none of the above apply, define a class for your component or part.
• Don't use any hardcoded values. All values you're using should ultimately refer back to the basic defined variables. Obvious exceptions are layout styles such as display, and relative units such as currentColor, em, and %. When referring to a value, again think about intent - if the usage is truly specific to the current component, feel free to just write spacer(4) or similar. In many cases though, there'll be some reasoning for using a value a certain way (example: $form-element-padding-x). Where applicable, create an intermediary variable named after the intent, and ensure it is used in all relevant places.
• Don't be afraid of inline CSS for layout styles**.** Some parts of CSS (like display and related properties) are more layout than they are style, so keeping them in HTML makes sense. I know using inline CSS sounds sacrilegious, and using utility clases to avoid it is common practice - but utility classes really just allow you to write inline CSS while being able to say "well technically this is a class, not inline CSS." Our base values are all available as CSS variables (example: var(--spacer-4)), and you should make use of them in that context, as well to ensure consistency. Only use inline CSS for non-reusable styles. If what you're writing is in any way a part of a reusable component or pattern, it should be a class rather than inline.

Migrating a page to the new design system

This section outlines the process of how to pick up, write and ship the migration of a page to the new design system.

If there are any problems with the migration, such as missing/incomplete components in the new system, or unresolvable incompatibilities between the old and new design systems, feel free to ask for help in the #rebrand channel.

• Refer to our list of pages that need to be converted to the new design system. Simply choose a page that's not assigned to anyone else yet and assign it to yourself. As with the regular Icebox, please make sure to only pick up one at a time unless you're waiting for a review.
• Create a deploy- branch for your migration, open up the page in question, then enable the design_system Rollout flag. Refresh the page and you'll likely be faced with a lot of broken/missing CSS. Some parts will work out of the box, as the new design automatically styles certain semantic HTML elements, and includes some temporary legacy styles for JS classes such as soft-hidden.
• Fix the missing styles by updating the layout to match and use the new design system's components, generally by changing element types and adding attributes and classes where necessary.
  • In almost all cases, you won't need to (and shouldn't) touch the new design's CSS files. As stated above, please ask in the #rebrand channel first if you feel like something's missing, as it may be preferable to use or adapt an existing component. All new CSS files should be components - we do not want to add any page-specific CSS.
  • If we do need to add something, it should generally be implemented as a standalone and reusable component, with an entry in Storybook. If there is something that we have to continue to support for the time being that isn't component-specific and generally doesn't fit into our design system, consider adding them to design/_legacy.scss - that file contains styles that we'll look to remove as soon as we can. Example: Styles for jQuery libraries.
  • Try not to remove any of the existing classes for now as the old design will have to keep functioning, as well.
  • Generally, you shouldn't need to touch any of the existing JS code other than to extend, not change how it represents certain states, but it is still preferable over adding legacy CSS to the new stylesheets.
• Once the page looks good and matches the new Figma, switch back to the old design and ensure everything still looks good. If there are any conflicts, resolve them in the old design files. If you have to be hacky about it there, don't worry - we'll throw the old files away soon enough anyway.
• All done? Awesome! Push your changes, make sure CI is green, enable the design_system Rollout flag on the branch app, create a PR, assign it to Maya and Jack for review, and reward yourself with a cookie (or another snack of your choice), because you deserve it.

Cleaning up

Right now, we're leaving all existing classes and image assets behind, as we need the existing design to continue functioning until we've migrated over all pages and switched them over in production.

Once we're ready to leave behind the old CSS and clean it up, we'll need to: