diff --git a/docs/rfc-002.md b/docs/rfc-002.md new file mode 100644 index 0000000000..4e12d65883 --- /dev/null +++ b/docs/rfc-002.md @@ -0,0 +1,95 @@ +# Create a universal component model for spacing + +## Problem and background + +We need a model for applying different spacing to components depending on their context, for example adding or removing bottom margin. This issue has been [extensively documented](https://trello.com/c/KEkNsxG3/60-implement-customisable-spacing-for-components) prior to now, but was put on hold as there was no urgent need for it. + +Organisation pages are being migrated out of whitehall and this has prompted the reopening of this issue. Specifically it is intended that the heading component be extended for use throughout these pages, which will require varying spacing being applied to it in different places. + +In addition, the recent [RFC relating to organisation pages colours](https://github.com/alphagov/govuk_publishing_components/pull/287) may provide a similar solution to this issue. + +## Proposed solution + +A helper sass file in the gem that provides shared classes for any component that wants them. The spacing model itself would be based on the `$gutter` variables and would be reduced by a third on mobile. + +Spacing model: + +| Class | Value | Desktop | Mobile | +| ------------------------------ | ------- | ------------------- | ------------------------------ | +| margin-top--gutter | 1 | $gutter | $gutter-two-thirds | +| margin-top--gutter-two-thirds | 2 | $gutter-two-thirds | ($gutter-two-thirds / 3) * 2 | +| margin-top--gutter-one-half | 3 | $gutter-one-half | ($gutter-one-half / 3) * 2 | +| margin-top--gutter-one-third | 4 | $gutter-one-third | ($gutter-one-third / 3) * 2 | +| margin-top--gutter-one-quarter | 5 | $gutter-one-quarter | ($gutter-one-quarter / 3) * 2 | + +This would be included for each of the following attributes (probably using a mixin to generate): + +- margin-top +- margin-right +- margin-bottom +- margin-left + +Sass example: + +``` +.margin-top--gutter { + margin-top: $gutter-two-thirds; + + @include media(tablet) { + margin-top: $gutter; + } +} +``` + +### In the component + +Components adapted to use this model could accept the parameter `margin` as an array of numbers, which would be used to add classes as appropriate. The array would contain four numbers, corresponding to top, right, bottom and left margins, for example `margins: [1, 0, 2, 0]` would give a margin value of 1 (gutter) to the top and a margin value of 2 (gutter-two-thirds) to the bottom. + +``` +margins ||= [] +margin_classes = [ + 'gutter', + 'gutter-two-thirds', + 'gutter-one-half', + 'gutter-one-third', + 'gutter-one-quarter' +] + +applied_margin_classes = "" + +if margins + margins.each do |margin| + applied_margin_classes << " margin-top--" + margin_classes[margin - 1] if margin + end +end + +