CSS Refactor Plan
My goal in this description is to speak candidly, respectfully, and decisively. These decisions are up for debate and we are open to changing anything in this document. When you comment, please try to be objective. Go straight for facts and numbers.
Based on the feedback we received from the FE team and others, I have revised the plan which you can find below.
Definitions for the sake of conversation
Component:
- When regarding CSS I mean component in the sense of Bootstrap Components. When talking about JS I mean it in the sense of VueJS Components.
Goals:
- To allow people to contribute to GitLab while writing minimal CSS, if any, which will keep our CSS consistent to a style guide.
- To reduce network latency from loading uneeded CSS.
- To componentize CSS in the same way bootstrap componentizes their CSS. Which will allow us to later create components for VueJS, and to create Ruby helpers.
- To greatly reduce UI Regressions.
- To reduce the time for UX to review MR's.
- To have a decisive way of writing new CSS that will follow styles similar OOCSS.
Problems to Solve:
- Our CSS classes are inconsistent and as a result are overidden and duplicated often.
- We have a loose attempt at componentizing but it does not follow a CSS organization method.
- Because our CSS is not organized or componentized (in the bootstrap sense of componentization, not VueJS sense), it is not easy to create styles for our VueJS components.
- CSS is not documented well in our guidelines. It's not easy to determine which classes are reusable.
Solutions to Problems:
- CSS will be on close observation during refactor. Any new CSS that needs to be written will be communicated to the FE Performance team. This is to make sure that we are aware of all things that need fixing.
- We will fix all inconsistent CSS classes issues.
- We will create a CSS framework that is based off of Bootstrap.
- This CSS library will live here: https://gitlab.com/gitlab-org/css-framework.
- This CSS library will have complete documentation similar to the Boostraps documentation.
- This documentation will include HTML samples of how to implement the components.
- We will also attempt to create a ruby helper for each component where it makes sense. We cannot guarantee that this step will be complete for each component.
Is this a fix or a rewrite:
- We will pull in Bootstrap, write the code on a per component basis, by doing we will be progressively rewriting each component 1 at a time.
This refactor will not produce VueJS Components.
- The creation of VueJS components will happen after the CSS Refactor. This refactor will set us up perfectly to create VueJS Components in the future. We will be cleaning up existing Vue components to match the style of the new CSS. Reasoning:
1. We have almost 1000 HAML files and tons of jQuery.
1. We need to be able to finish this refactor. We need to constantly deliver in order to be successful.
1. If we create VueJS components we need to implement them. We cannot fix the css, refactor css components, implement everywhere, insure quality, and the do the whole process for Vue components. That would be a never ending massive undertaking.
1. We do not have a plan for the implementation of VueJS components. That plan itself would need review and consensus just as we have done here.
1. Every file changed creates the opportunity for a bug.
1. Our CSS debt is massive we need to climb out of that debt first.
How:
- We will define the components that will be refactored for each milestone.
- For each component (assignee may change):
-
@iamphill find all the inconsistencies for the component (e.g.
btn-success
vsbtn-create
) - @jschatz1 will create the new component in css-framework based off of existing Bootstrap styles where possible. Or create component from scratch if it doesn't exist in Bootstrap.
- @jschatz1 will create documentation for the component.
- @jschatz1 will port component to GL for use in application.
- @ClemMakesApps will optionally create a ruby help for easy implementation.
- @ClemMakesApps will implement the new component everywhere it exists.
- @okoghenun will use browserstack to create tests that we can run to confirm UI consistencies. We will link UX reviews to these tests for approval. Tests will run on css-framework and GL.com. He can work ahead of the team if necessary.
- FE will review implementation from our team. FE will review implementation from outside our team.
- UX will review screenshots, CSS and HTML for approval.
cc @psimyn @ClemMakesApps @iamphill @okoghenun @timzallmann
Useful Links
- https://brand.ai/git-lab/primary-brand
- https://gitlab-org.gitlab.io/gitlab-design/hosted/gitlab-elements-spec-previews/
Stages
Edited by Jacob Schatz