I was consulting for a company the other day, and we got into an interesting conversation on evaluating how to do platform customizations, and then reading some recent posts of common topics that come up, thought it might be useful to try and write the outcomes down.

For the sake of this discussion, focused on CSS/HTML changes, not programmatic or API based, which leads to the first point.

1. Is it possible? There tends to be a lot of confusion on what is and is not editable by CSS modifications. CSS at its core is the style of a website, how it looks. It is generally not used for adding additional items (this is html or structure) or robust actions (historically this is javascript, which we generally cannot add to the platform safely.) Yes, modern CSS does allow for some common actions, and you can build quite complex ones within it, so this one is not a dealbreaker, but unlike in scripting, the structure still needs to exist on the page already in order to leverage these, so unless you are building the structure entirely yourself first, it often will not work in Docebo.
2. Can it be achieved in a platform way? Before touching a CSS modification, make sure it isn’t doable, or at least close enough, with a different built in platform feature. There are two common mechanisms here to make sure to check out first:
   1. Simply adjusting a setting. Yes there are a lot, so just make sure to do the due diligence of checking, maybe asking support and around here to make sure not missing something.
      Remember, sometimes it may not be exactly what you envisioned, but is close enough that it might be worth it to just accept the middle ground.
   2. Are you modifying text? Always, always always, check the localization tool first. If you are not familiar with the tool,it is the platform way to support multiple languages, and it was built in a way that allows you to modify the text displayed in many areas of the platform. This is always preferable as it replaces the text at the database level and has less maintenance to it in the long term as Docebo is aware of the current fields and will need to mitigate effects of any platform changes long term, if you simply override the text with something like CSS, they have no way of accounting for that, every release, every month, is a potential for breaking your change without notice. For more info on the tool make sure to check out the support article here, or search around the community, there are a lot of threads on people using it.
3. Are you a big mobile app user? If you are, it is important to know any changes added to the ‘Custom Styles’ in the ‘Configure Look and Branding’ area of the platform, where most people put their CSS modifications, will be ignored entirely by the Mobile App. This means if you are doing heavy visual changes, and use the app heavily, you could end up with two very different experiences for the end user, which is generally not a great UX design approach. There are some ways around this, like using all inline CSS instead within HTML widgets, but this is far more restricting in what you can and can’t do and also increases the maintenance since you have to modify each occurrence individually.
4. Can you modify the item specific enough? Since we are stuck with the structure we are given, sometimes there is not a good CSS class/id or combination of them to be able to select what we want to edit directly. This results in some techniques like:
   1. ‘selecting the nth item on a list’ for modifying menu items, that are not really safe as they can be easily broken and end up with unexpected results without you realizing down the line, especially when new features are released or turned on/off on your instance.
   2. Applying too broad of a selector. Yes this solves your current issue, but it can impact other areas of the platform you did not realize or intend causing issues to users. 
5. Modify existing or frame in an external solve? So far, most of the solves focus on modifying existing items. There are situations where it makes more sense to either build and host the content some place else, or use a service that let’s you iframe content into other webpages. This is a bit of a personal company choice based on what access you have to resources like a server to host content. If you do, remember, a lot of the tools you are probably already using to build course content, can usually export to HTML and be used to build things like banners and notices in a tool you are comfortable in.
6. What is the maintenance cost? Speaking of increased maintenance. Any modification to the platform adds additional maintenance cost. Not straight cash cost, although it can, here we are talking time. All the platform wide CSS changes you make are based on the underlying and existing structure Docebo controls. This means every time the platform is updated, theoretically every change needs to be checked and potentially fixed to handle any underlying changes. While this does not seem like a big deal at first, these kinds of thing stack over time and can become untenable. I use a need vs. preference test for these choices typically, is the change actually needed to improve the experience or is it simply a personal preference that I am able to apply to the platform? Each organization has to establish their own metric for this, but be careful of the personal preference asks. 
7. Is it accessible? This is actually my personal number 1, as if it is not, then it shouldn’t be done. It is very easy for users to make changes that work for them, but do not work for other types of users. It may be a disability, or a preferable way to do their learning, or simply just keeping the content working across different device/screen/input types. Since we have limited access to add changes, workarounds often get used (honestly, abused) to achieve results that can result in non-accessible outcomes. This is not great. If you are not aware of the benefits of inclusive design, strongly recommend reading up on it, the more all content creators/curators in the world embrace it, the better everyone is. Here is a simple beginning article that does a good job of the basics and points to some great resources for more.
8. Should we do it? While this has been covered in pieces throughout the previous steps, always always always do a dedicated stop and ask, ok we have a potential solve, but should we. Maintenance and accessibility are usually the two biggest factors for me, sometimes some internal politics factor in here as well. Everyone will have their own reasons, as long as you did the evaluation, that is the important step.

This is what we came up with. Anything you think we missed or you use to help make your choices on CSS/HTML modifications?