Refactor spacing API #779

hannalaakso · 2018-06-12T07:58:30Z

This PR:

Defines the spacing variables in a map, rather than as multiple variables, allowing control over error messaging when an incorrect variable is used and allows them to be overridden by consumers.

In detail, it:

Adds a new helper govuk-spacing to fetching single point spacing.
Moves single point spacing variables inside a map.
Moves responsive spacing maps inside a collective map $govuk-spacing-responsive-scale and updates the helper.
Removes the old $govuk-spacing-responsive-scale map we created for generating overrides as the overrides can now use the new scale map 🎉
Possibly controversial: makes govuk-responsive-spacing() a private mixin as it should only be used via govuk-responsive-margin and govuk-responsive-padding.
Updates other layers to use the govuk-spacing function and the new responsive spacing map.
Updates tests accordingly and adds new tests for govuk-spacing()
Updates comments for sass-docs.

Other:

$govuk-gutter is now hardcoded as govuk-spacing cannot be accessed from inside the settings layer. However if we think it should be coupled more tightly with the spacing scale, we could maybe use map-get to fetch a specific spacing point in settings... I’ve created an issue to review this.

Note: the PR is easiest to review commit-by-commit.

https://trello.com/c/0IDTgRtF/1112-provide-a-defined-public-api-for-govuk-frontend-spacing

36degrees

Raised a few very minor consistency things, but otherwise this looks really good – great commit structure and messages 👌

36degrees · 2018-06-12T08:03:10Z

src/settings/_spacing.scss

+///
+/// These definitions are used to generate responsive spacing that adapts
+/// according to the breakpoints (see 'helpers/spacing'). These maps should be
+/// used wherever possible to standardise responsive spacing.



Picky, but can we add the /// to the blank lines to so that it reads as one connected comment block?

36degrees · 2018-06-12T08:04:02Z

src/helpers/_spacing.scss

 ///
-/// @param {Map} $scale-map - Map of breakpoints and spacing values
+/// @param {Number} $responsive-spacing-point - Point on the responsive spacing
+/// scale, corresponds to a map of breakpoints and spacing values


Would be good to indent the second line like we have on :48

36degrees · 2018-06-12T08:04:39Z

src/helpers/_spacing.scss

-    + "responsive spacing scale.";
+  $actual-input-type: type-of($responsive-spacing-point);
+  @if $actual-input-type != "number" {
+    @error "Expected a number (integer), but got a "


I think this is short enough it'll fit on one line?

36degrees · 2018-06-12T08:05:13Z

src/helpers/_spacing.scss

 /// @param {String} $direction [all] - Direction to add spacing to
 ///   (`top`, `right`, `bottom`, `left`, `all`)
 /// @param {Boolean} $important [false] - Whether to mark as `!important`
 /// @param {Number} $adjustment [false] - Offset to adjust spacing by
 ///
+/// @example scss


36degrees · 2018-06-12T08:07:38Z

src/helpers/spacing.test.js

@@ -67,7 +110,7 @@ describe('@mixin govuk-responsive-spacing', () => {
            padding-top: 25px; } }`)
  })

-  it('throws an exception when passed anything other than a map', async () => {
+  it('throws an exception when passed anything other than a number', async () => {


Technically '14px' is a number in Sass, so maybe 'throws an exception when passed a non-existent point' or similar?

Put single spacing points in a map. Put responsive spacing maps inside a collective map. Remove old `$govuk-spacing-responsive-scale` map as the overrides can now use the new scale map :) Update comments for sass-doc.

kr8n3r · 2018-06-12T11:00:50Z

src/settings/_spacing.scss

-// You can define different behaviour on tablet and desktop. The 'null'
-// breakpoint is for mobile.
+$govuk-spacing-points: (
+  0: 0,


in there any point in having 0 in teh scale, since we've used 0 where needed instead of `govuk-spacing(0)?

.govuk-header--full-width { padding: 0 govuk-spacing(3); }

Yes, because it means there's an override generated for it, so you can remove margins.

36degrees

Sorry, one more thing I didn't spot first time round. 👀

36degrees · 2018-06-12T15:58:12Z

src/helpers/_spacing.scss

 /// @param {String} $property - Property to add spacing to (e.g. 'margin')
 /// @param {String} $direction [all] - Direction to add spacing to
 ///   (`top`, `right`, `bottom`, `left`, `all`)
 /// @param {Boolean} $important [false] - Whether to mark as `!important`
 /// @param {Number} $adjustment [false] - Offset to adjust spacing by
 ///
-/// @access public
+/// @access private


If this is private then the mixin name should be prefixed with an underscore (_govuk-responsive-spacing). Change makes sense I think as you can achieve everything with govuk-responsive-margin and govuk-responsive-padding?

36degrees · 2018-06-12T15:59:42Z

src/helpers/_spacing.scss

-@mixin govuk-responsive-margin($scale-map, $direction: "all", $important: false, $adjustment: false) {
-  @include govuk-responsive-spacing($scale-map, "margin", $direction, $important, $adjustment);
+@mixin govuk-responsive-margin($responsive-spacing-point, $direction: "all", $important: false, $adjustment: false) {
+  @include govuk-responsive-spacing($responsive-spacing-point, "margin", $direction, $important, $adjustment);


We could pass all arguments like we do for mq if we wanted to avoid having to maintain the same signature in three places (though we'd need to update the docs anyway I guess…)

Thank @36degrees. As discussed IRL, we need to pass the property (margin / padding) through to _ govuk-responsive-spacing so $args... wouldn't work in this scenario.

All helpers now use single point spacing which is used to fetch maps from `settings/spacing`. Responsive helper now uses `map-get` to fetch spacing map, instead of accessing the variables directly. Add error checking. Update comments for sass-doc.

36degrees · 2018-06-13T10:11:21Z

src/overrides/_spacing.scss

@@ -23,28 +23,30 @@ $spacing-directions: (
 // .govuk-\!-mt-r1 {
 //   margin-top: [whatever spacing point 1 is...]
 // }
+///


Can the rest of this code block be updated to Sassdoc? (triple slash, use @example, document the parameters)?

For sure, good shout @36degrees. Done now.

Point from spacing scale is now used to generate overrides, instead of passing the map through directly. Also prefix `generate-spacing-overrides()` with `govuk-`.

Add tests for new `govuk-spacing` function

Use `govuk-spacing()` instead `$govuk-spacing-*'` `$govuk-gutter` is problematic as it cannot call `govuk-spacing()` helper from the `settings` layer. We *think* that the gutter variables can be decoupled from the spacing scale so this commit hardcodes them. However there's now a GitHub issue added to review this relationship.

Update `govuk-responsive-margin` and `govuk-responsive-padding` to use new spacing maps.

kr8n3r · 2018-06-13T15:21:05Z

src/overrides/_spacing.scss

+/// @param {String} $property-shorthand - Shorthand representation of property, eg. "m" for "margin"
+///
+/// @example scss
+///   .govuk-\!-m-r0 {


as a note: this will need to be updated in #786

kr8n3r

happy it address all comments

💯

36degrees

👍

govuk-design-system-ci temporarily deployed to govuk-frontend-review-pr-779 June 12, 2018 07:58 Inactive

hannalaakso mentioned this pull request Jun 12, 2018

Review if gutter variables need to coupled with spacing scale #780

Closed

36degrees reviewed Jun 12, 2018

View reviewed changes

hannalaakso force-pushed the spacing-api branch from 274494c to 518375f Compare June 12, 2018 09:39

govuk-design-system-ci temporarily deployed to govuk-frontend-review-pr-779 June 12, 2018 09:39 Inactive

Move spacing variables into Sass maps

3ab6772

Put single spacing points in a map. Put responsive spacing maps inside a collective map. Remove old `$govuk-spacing-responsive-scale` map as the overrides can now use the new scale map :) Update comments for sass-doc.

hannalaakso force-pushed the spacing-api branch from 518375f to 1f062b5 Compare June 12, 2018 09:58

govuk-design-system-ci temporarily deployed to govuk-frontend-review-pr-779 June 12, 2018 09:58 Inactive

kr8n3r reviewed Jun 12, 2018

View reviewed changes

36degrees reviewed Jun 12, 2018

View reviewed changes

hannalaakso force-pushed the spacing-api branch from 1f062b5 to d2a42d7 Compare June 13, 2018 08:26

govuk-design-system-ci temporarily deployed to govuk-frontend-review-pr-779 June 13, 2018 08:26 Inactive

36degrees reviewed Jun 13, 2018

View reviewed changes

hannalaakso added 5 commits June 13, 2018 15:43

Update override mixin to use new maps.

ae6e4a9

Point from spacing scale is now used to generate overrides, instead of passing the map through directly. Also prefix `generate-spacing-overrides()` with `govuk-`.

Update tests to use new spacing maps.

e7f1e2f

Add tests for new `govuk-spacing` function

Update Sass margin and padding to new spacing maps

0a04228

Update `govuk-responsive-margin` and `govuk-responsive-padding` to use new spacing maps.

Update changelog

49d64ee

hannalaakso force-pushed the spacing-api branch from d2a42d7 to 49d64ee Compare June 13, 2018 14:44

govuk-design-system-ci deployed to govuk-frontend-review-pr-779 June 13, 2018 14:44 View deployment

kr8n3r reviewed Jun 13, 2018

View reviewed changes

kr8n3r approved these changes Jun 13, 2018

View reviewed changes

36degrees approved these changes Jun 13, 2018

View reviewed changes

hannalaakso merged commit 5198d71 into master Jun 13, 2018

hannalaakso deleted the spacing-api branch June 13, 2018 15:30

hannalaakso mentioned this pull request Jun 14, 2018

Release v0.0.32 #791

Merged

36degrees mentioned this pull request Jun 21, 2018

Theming: Move spacing scale to t-shirt sizing #642

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Refactor spacing API #779

Refactor spacing API #779

hannalaakso commented Jun 12, 2018 •

edited

36degrees left a comment

36degrees Jun 12, 2018

36degrees Jun 12, 2018

36degrees Jun 12, 2018

36degrees Jun 12, 2018

36degrees Jun 12, 2018

kr8n3r Jun 12, 2018

36degrees Jun 12, 2018

36degrees left a comment

36degrees Jun 12, 2018

36degrees Jun 12, 2018

hannalaakso Jun 13, 2018

36degrees Jun 13, 2018

hannalaakso Jun 13, 2018

kr8n3r Jun 13, 2018

kr8n3r left a comment

36degrees left a comment

Refactor spacing API #779

Refactor spacing API #779

Conversation

hannalaakso commented Jun 12, 2018 • edited

36degrees left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

36degrees left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kr8n3r left a comment

Choose a reason for hiding this comment

36degrees left a comment

Choose a reason for hiding this comment

hannalaakso commented Jun 12, 2018 •

edited