Add government department colours to components

docs/rfc-001.md

@@ -0,0 +1,124 @@
+# Add government department brand colours to gem for use by components
+
+## Problem and background
+
+Organisation pages ([example](https://www.gov.uk/government/organisations/attorney-generals-office)) have their own brand, which includes specific colours applied to links and borders. These colours are pulled in from [govuk_frontend_toolkit](https://github.com/alphagov/govuk_frontend_toolkit/blob/master/stylesheets/colours/_organisation.scss) using a [mixin](https://github.com/alphagov/whitehall/blob/master/app/assets/stylesheets/frontend/views/_organisations.scss#L855-L858) to generate a range of classes.
+
+Most organisations have one colour for borders and one for links, even if they are broadly the same colour. These are applied to the existing structure of the frontend of whitehall.
+
+The structure of the new organisation pages (to be built in collections) uses components, which are individual and isolated. To reproduce this approach in the same way would mean adding all of the CSS for all of the colour options to all of the components, dramatically increasing the size of the CSS involved and introducing much duplication.
+
+## Proposed solution
+
+### In the gem
+
+All colour classes are included in a helper Sass file in the gem.
+
+Sass in the gem looks like this:
+
+```
+@import "colours/organisation";
+
+@mixin organisation-brand-colour($selector, $property, $websafe: false) {
+  @each $organisation in $all-organisation-brand-colours {
+    .color-#{$selector}--#{nth($organisation, 1)} .color-#{$selector} {
+      @if $websafe {
+        #{$property}: nth($organisation, 3);
+      }
+      @else {
+        #{$property}: nth($organisation, 2);
+      }
+    }
+  }
+}
+
+@include organisation-brand-colour("link", color, true);
+@include organisation-brand-colour("border", border-color);
+```
+
+This is included in the `_all_components.scss` file.
+
+CSS in the gem looks like this:
+
+```
+.color-link--department-for-work-and-pensions .color-link {
+  border-color: #8f1111;
+}
+
+.color-border--department-for-work-and-pensions .color-border {
+  border-color: #9f1888;
+}
+```
+
+etc.
+
+### In the component
+
+Pass component parameters for link_colour and border_color as required, as strings that match the pre-defined list e.g. 'department-for-work-and-pensions'.
+
+Component takes the link parameter and adds a class e.g. 'color-link--department-for-work-and-pensions' to the component and 'color-link' to the relevant elements.
+
+Component looks like this:
+
+```
+<div class="app-c-component color-link--department-for-work-and-pensions">
+  <a href="#" class="color-link">
+    a link
+  </a>
+</div>
+```
+
+Component takes border colour and adds the class e.g. 'color-border--department-for-joy' to the component and 'color-border' to the relevant elements.
+
+Component looks like this:
+
+```
+<div class="app-c-component color-border--department-for-joy">
+  <span class="app-c-component__title color-border">
+    an element
+  </span>
+</div>
+```
+
+Sass in the component looks like this:
+
+```
+.app-c-component__title {
+  border-style: none none none solid;
+  border-width: 2px;
+}
+```
+
+The border-color attribute is set in the gem. This way the component retains control over the border position and size and the generic classes can be as non-specific as possible.
+
+## Other approaches considered
+
+Pass through the hex code of the desired colour and it gets inserted as an inline style attribute
+
+- no absolutely not.
+- also we don't have the hex code in the content item, would require more work to add it and would mix styles and backend, undesirable
+
+Pass through the name of the colour and the component will add the style that matches
+
+- would add approx 2KB of CSS to every component where we need this (there are nearly 60 colours)
+
+Generate needed styles inline as a style tag within the template
+
+- given the parameter 'department-for-education' generate a style tag in the template like `app-c-component--<%= link_colour %> { color: <%= get_colour(link_colour) %>}`
+- we don't do inline styles
+- would need a helper method that already contained all the hex codes associated with their department names, again mixing styles and backend, which is undesirable
+
+## Decisions explained
+
+- originally wanted a flatter class structure e.g. `.color-link--department-for-agriculture { }` but this is overridden by the default styles for :visited etc. so either we have to write all those out explicitly or add an extra class (the extra class seemed a shorter way of doing it and allows more flexibility in future e.g. if a component suddenly required one link that wasn't that colour, you could just omit the class on that link)
+- want to avoid any generic rules like `.color--no-10 a {}` as this could cause problems for developers later
+- writing general classes for colour like this avoids having to write component specific classes, even though this goes against the component principle of them being isolated (although most components rely on some external CSS already, e.g. reset)
+
+## Assumptions made (may not be true)
+
+- specific class for border or link can be applied to all elements, this may not be the case if the component is simply passed a block of HTML, in which case we might have to go back and modify this approach to the undesirable `.color-no-10 a {}` approach
+
+## Likely problems
+
+- can we have any components using this that aren't in the gem? Due to the tight coupling it seems like they should be in the same place as the colours CSS but that would mean promoting more components to the gem, more work, less time
+