From 1fdf7e7564bf00a6ac63f768b5e95a9c0a87689e Mon Sep 17 00:00:00 2001 From: Inayaili Leon Date: Thu, 14 May 2020 09:41:45 +0100 Subject: [PATCH 1/5] Spacing doc draft --- docs/spacing.md | 92 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 docs/spacing.md diff --git a/docs/spacing.md b/docs/spacing.md new file mode 100644 index 000000000..31ee8426f --- /dev/null +++ b/docs/spacing.md @@ -0,0 +1,92 @@ +# Spacing + +Careful spacing is key for the user to understand connections and hierarchies between elements, and for an interface to feel pleasant. + +## Scale + +Primer follows a base-8 scale, as it allows for significant flexibility when defining a variety of spacing values within an interface. + +`[list of spacing utilities]` + +For very small components where 8 pixel spacing is too large, you can use 4 pixels. + +## Responsive breakpoints + +You can define different spacing values for different breakpoints, so the interface can better adapt to the available space. + +`[Example: component with larger margin around it in large screen, vs smaller margin in small screen]` + +In code, margins can be defined per breakpoint, where different breakpoints have a different margin applied. + +`[Example: mb-sm-2 mb-md-3 mb-lg-4]` + +## Applying spacing + +The general rule when using Primer is to apply spacing in increments of 8 pixels, as provided by the spacing utilities. + +In some cases, for very small components and in denser areas of the UI, you can use 4 pixels. + +`[Example: text and icon button]` + +Primer components have inner spacing built-in, so in most cases you’ll only need to consider vertical spacing between components. + +Do/Don’t: Using custom values? + +## Relationships + +Elements that are close together are perceived as being related or part of the same group, while elements that are far apart from each other feel unrelated. + +`[Examples: cancel, save buttons; repo top nav buttons]` + +Alignment +- Do / Don’t + +## Hierarchy + +Do: Add more white space around components that are more important. + +`[Examples: titles]` + +Note: Editorial content can have more generous spacing. + +`[Examples: first use cards, new features cards]` + +## Consistency + +Do: Apply the same spacing values to similar components. + +`[Example: all items in the sidebar have the same vertical distance]` + +## Density + +`[Examples: ]` + +## Optical adjustments + +Icons + +Inline spacing + +## Common spacing values + +Small components usually have 8px between them. In some cases, for very small buttons, you can use 4px. + +`[Example: buttons side by side, labels, icon+text]` + +The most common value when stacking components vertically is 16px. + +`[Example: issue header above first comment, sidebar, stacked boxes]` + +## Learn more about spacing +If you’d like to read more about spacing in UI design, we recommend: + +- + + +## Related + +- [Primer CSS - Support - Spacing](https://primer.style/css/support/spacing) +- [Primer CSS - Utilities - Padding](https://primer.style/css/utilities/padding) +- [Primer CSS - Utilities - Margin](https://primer.style/css/utilities/margin) +- [Primer CSS - Utilities - Borders](https://primer.style/css/utilities/borders) +- [Primer Primitives - Spacing](https://github.com/primer/primitives/blob/master/primitives/spacing.ts) From 6b4d49de060fc97503fcccfd8c00acf57b8edc39 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Inayaili=20Le=C3=B3n?= Date: Tue, 19 May 2020 15:59:50 +0100 Subject: [PATCH 2/5] Added "read more" links --- docs/spacing.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/spacing.md b/docs/spacing.md index 31ee8426f..e473f11d5 100644 --- a/docs/spacing.md +++ b/docs/spacing.md @@ -80,8 +80,9 @@ The most common value when stacking components vertically is 16px. ## Learn more about spacing If you’d like to read more about spacing in UI design, we recommend: -- - +- [Elements of design](https://www.invisionapp.com/design-defined/elements-of-design/) +- [Design principles – Gestalt, white space and perception](https://manifesto.co.uk/design-principles-gestalt-white-space-perception/) +- The Principle of spacing in UI design, [Part 1](https://medium.com/dwarves-design/the-principle-of-spacing-in-ui-design-part-1-3354d0d65e51) and [Part 2](https://medium.com/dwarves-design/the-principle-of-spacing-part-2-e3cf31b909fa) ## Related From 57ad5ec59f34dace35b0205b2189c87df1abc997 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Inayaili=20Le=C3=B3n?= Date: Wed, 9 Sep 2020 15:18:04 +0100 Subject: [PATCH 3/5] Updates to spacing --- docs/spacing.md | 31 +++++++++++++++++++++++-------- 1 file changed, 23 insertions(+), 8 deletions(-) diff --git a/docs/spacing.md b/docs/spacing.md index e473f11d5..ace2ced4e 100644 --- a/docs/spacing.md +++ b/docs/spacing.md @@ -4,9 +4,9 @@ Careful spacing is key for the user to understand connections and hierarchies be ## Scale -Primer follows a base-8 scale, as it allows for significant flexibility when defining a variety of spacing values within an interface. +Primer follows a base-8 scale, as it allows for significant flexibility when defining a variety of spacing values within an interface. -`[list of spacing utilities]` +The possible values are: 0, 4, 8, 16, 24, 32, 40, 48 For very small components where 8 pixel spacing is too large, you can use 4 pixels. @@ -28,9 +28,17 @@ In some cases, for very small components and in denser areas of the UI, you can `[Example: text and icon button]` -Primer components have inner spacing built-in, so in most cases you’ll only need to consider vertical spacing between components. +Primer components have padding built-in, so in most cases you’ll only need to consider vertical spacing *between* components. -Do/Don’t: Using custom values? +In some cases, the spacing values inside components don't follow the values in the scale, but the total size of the component should always follow the scale. + +`[Example: the padding inside a button may be 3px or 5px but the total height is 32px]` + +**Do:** +- Use the spacing values available in Primer. + +**Don’t:** +- Don't apply custom spacing values. ## Relationships @@ -38,8 +46,11 @@ Elements that are close together are perceived as being related or part of the s `[Examples: cancel, save buttons; repo top nav buttons]` -Alignment -- Do / Don’t +## Alignment + +As a general rule, elements should align to other elements' outer box, and not try to align to the content within a box. + +`[Example: text outside and above a table/list should align to the edge of the table (and not to the content within the rows]` ## Hierarchy @@ -63,9 +74,9 @@ Do: Apply the same spacing values to similar components. ## Optical adjustments -Icons +In some cases, optical adjustments may break from the scale. -Inline spacing +`[Example: avatar on commits in repo landing page align optically with file icons below]` ## Common spacing values @@ -77,6 +88,10 @@ The most common value when stacking components vertically is 16px. `[Example: issue header above first comment, sidebar, stacked boxes]` +Generally, Primer elements have "squished" padding, where the vertical padding is smaller than the horizontal padding. + +`[Example: squished padding element, like a button.]` + ## Learn more about spacing If you’d like to read more about spacing in UI design, we recommend: From efc4fdd63bacd68eb7429278a5d861fecbadbf2b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Inayaili=20Le=C3=B3n?= Date: Wed, 9 Sep 2020 15:41:08 +0100 Subject: [PATCH 4/5] More updates --- docs/spacing.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/spacing.md b/docs/spacing.md index ace2ced4e..fc8ecdcb0 100644 --- a/docs/spacing.md +++ b/docs/spacing.md @@ -16,9 +16,7 @@ You can define different spacing values for different breakpoints, so the interf `[Example: component with larger margin around it in large screen, vs smaller margin in small screen]` -In code, margins can be defined per breakpoint, where different breakpoints have a different margin applied. - -`[Example: mb-sm-2 mb-md-3 mb-lg-4]` +In code, margins can be defined per breakpoint, where different breakpoints have a different margin applied. For example, applying the classes `mb-sm-2`, `mb-md-3`, and `mb-lg-4` to one component would translate into: `margin-bottom: 8px` in small screens (`mb-sm-2`), `margin-bottom: 16px` in medium screens (`mb-md-3`), and `margin-bottom: 24px` in large screens(`mb-lg-4`). ## Applying spacing @@ -54,7 +52,7 @@ As a general rule, elements should align to other elements' outer box, and not t ## Hierarchy -Do: Add more white space around components that are more important. +**Do:** Add more white space around components that are more important. `[Examples: titles]` @@ -64,13 +62,15 @@ Note: Editorial content can have more generous spacing. ## Consistency -Do: Apply the same spacing values to similar components. +**Do:** Apply the same spacing values to similar components. `[Example: all items in the sidebar have the same vertical distance]` ## Density -`[Examples: ]` +Some screens and flows require a denser layout, with smaller elements and less space between components, depending on the type of action users most often take. In these cases, use the smaller values of the spacing scale. + +`[Examples: high density screen, or part of screen]` ## Optical adjustments From cae2c494db96ff83e649fcb3c5cf2db5a11e334a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Inayaili=20Le=C3=B3n?= Date: Tue, 5 Jan 2021 16:27:22 +0000 Subject: [PATCH 5/5] Update docs/spacing.md --- docs/spacing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spacing.md b/docs/spacing.md index fc8ecdcb0..2e9018a6d 100644 --- a/docs/spacing.md +++ b/docs/spacing.md @@ -46,7 +46,7 @@ Elements that are close together are perceived as being related or part of the s ## Alignment -As a general rule, elements should align to other elements' outer box, and not try to align to the content within a box. +As a general rule, elements should align to other elements' outer box, and not try to align to the content inside a box. `[Example: text outside and above a table/list should align to the edge of the table (and not to the content within the rows]`