Customization documentation

[rjimenezda]

Problem We need to improve the documentation regarding airship customization.

Proposed solution We should at least:

1. Provide an example of a customized dashboard (dark theme maybe?)
2. Include it in the docs.

Consider:

• Document all CSS variables. The component ones should already be documented, but the airship ones not.

By doing point 1, we might get a feeling of what the state of customization is, and probably spawn some new issues.

[rjimenezda]

Some crazy ideas I've had regarding this:

• Something like vuetify's theme geneartor would be very interesting, but totally out of scope at this point. I think the dashboard with a theme switcher is more than enough right now.

• It would be great having a 'formal' way of defining which CSS variables each component / styled element uses, so we could parse them and work with them. The docs could then have little theme switchers for each one, so you can see how they look on different scenarios.

[elenatorro]

About your second crazy idea, @rjimenezda, I'd like to expand it a bit more:

I think that, before adding it to the documentation, we've to make some changes to the variables defined in each component.

After playing around with airship trying to do a dark theme, I think we should do the following:

1. First of all, distinguish between global custom variables and component custom variables.
2. Each component must have their own css variables for customization (component custom variables) for all the fields we want to customize. It may be possible to have other variables (if we want to calculate something, but IMO those can be scss variables, I didn't come up with a use case yet but if you do please tell me!)
3. Each component custom variables must be fallback, by default, one of our global custom variables.

So there are at the end 2 levels of customization: global and by component. Depending on the variables we want to use in our theme or depending on the business case, I think we should offer the possibility of changing them in every component. I think this is the easiest way to offer customization.

Regarding documentation, we'd have to separate global variables vs component variables, and add an example by component. I'd do that first than devleoping a generator (which I think is an awesome idea)

It implies changing all the components and it may seem a lot of work, any feedback is appreciated ✨

[ivanmalagon]

In case you don't know, @IagoLast made a guideline of how CSS variables should be structured and named at https://github.com/CartoDB/airship/blob/master/DEVELOPERS.md#css-variables

You've come to the same conclusion: global custom variables and specific variables that relies on their initial values on the global ones. Changing the global should reflect the change in every aspect but having the chance to customize at component level.

[elenatorro]

You're totally right! I didn't read it when I wrote this, but it's great and it's very well explained, taking it into account 👌