feat: Add and use tokens for inside space (#1093)

Co-authored-by: Aram <[email protected]>
Amsterdam · Mar 7, 2024 · 81c9f7a · 81c9f7a
1 parent 2cd047b
commit 81c9f7a
Show file tree

Hide file tree

Showing 21 changed files with 115 additions and 50 deletions.
diff --git a/packages/css/src/components/accordion/accordion.scss b/packages/css/src/components/accordion/accordion.scss
@@ -24,8 +24,8 @@
   font-weight: var(--amsterdam-accordion-button-font-weight);
   justify-content: space-between;
   line-height: var(--amsterdam-accordion-button-line-height);
-  padding-block: 0.75rem;
-  padding-inline: 1rem;
+  padding-block: var(--amsterdam-accordion-button-padding-block);
+  padding-inline: var(--amsterdam-accordion-button-padding-inline);
   width: 100%;
 
   &:focus {
@@ -54,8 +54,8 @@
 
 .amsterdam-accordion__panel {
   display: none;
-  padding-block: 1rem;
-  padding-inline: 1rem;
+  padding-block: var(--amsterdam-accordion-panel-padding-block);
+  padding-inline: var(--amsterdam-accordion-panel-padding-inline);
 }
 
 .amsterdam-accordion__panel--expanded {

diff --git a/packages/css/src/components/dialog/dialog.scss b/packages/css/src/components/dialog/dialog.scss
@@ -26,6 +26,8 @@
   gap: var(--amsterdam-dialog-form-gap);
   grid-template-rows: auto 1fr auto;
   max-block-size: var(--amsterdam-dialog-form-max-block-size);
+
+  // TODO Decide on these widths
   padding-block: var(--amsterdam-dialog-form-padding-block);
   padding-inline: var(--amsterdam-dialog-form-padding-inline);
 }

diff --git a/packages/css/src/components/header/header.scss b/packages/css/src/components/header/header.scss
@@ -9,7 +9,7 @@
   align-items: center;
   display: flex;
   flex-wrap: wrap;
-  padding-block: 1rem;
+  padding-block: var(--amsterdam-header-padding-block);
   row-gap: 1.5rem;
 
   @media screen and (min-width: $amsterdam-breakpoint-wide) {
@@ -38,7 +38,7 @@
 
 .amsterdam-header__menu {
   flex: 1;
-  padding-inline-start: var(--amsterdam-page-menu-column-gap);
+  padding-inline-start: var(--amsterdam-page-menu-column-gap); // TODO Don’t use tokens of another component
   text-align: end;
 
   @media screen and (min-width: $amsterdam-breakpoint-wide) {

diff --git a/packages/css/src/components/mega-menu/mega-menu.scss b/packages/css/src/components/mega-menu/mega-menu.scss
@@ -6,6 +6,8 @@
 .amsterdam-mega-menu__list-category {
   column-gap: var(--amsterdam-mega-menu-list-category-column-gap);
   column-width: var(--amsterdam-mega-menu-list-category-column-width);
+
+  // TODO Move to bottom margin of heading
   padding-block-start: var(--amsterdam-mega-menu-list-category-padding-block-start);
 
   &:not(:last-child) {

diff --git a/packages/css/src/components/pagination/pagination.scss b/packages/css/src/components/pagination/pagination.scss
@@ -38,7 +38,7 @@
   display: flex;
   gap: 0.5rem;
   outline-offset: var(--amsterdam-pagination-button-outline-offset);
-  padding-inline: 0.75rem;
+  padding-inline: var(--amsterdam-pagination-button-padding-inline);
   text-decoration-line: var(--amsterdam-pagination-button-text-decoration-line);
   text-decoration-thickness: var(--amsterdam-pagination-button-text-decoration-thickness);
   text-underline-offset: var(--amsterdam-pagination-button-text-underline-offset);

diff --git a/packages/css/src/components/search-field/search-field.scss b/packages/css/src/components/search-field/search-field.scss
@@ -23,8 +23,8 @@
   font-weight: var(--amsterdam-search-field-input-font-weight);
   line-height: var(--amsterdam-search-field-input-line-height);
   outline-offset: var(--amsterdam-search-field-input-outline-offset);
-  padding-block: 0.5rem;
-  padding-inline: 1rem;
+  padding-block: var(--amsterdam-search-field-input-padding-block);
+  padding-inline: var(--amsterdam-search-field-input-padding-inline);
   touch-action: manipulation;
   width: 100%;
 
@@ -58,8 +58,10 @@
   color: var(--amsterdam-search-field-button-color);
   cursor: pointer;
   outline-offset: var(--amsterdam-search-field-button-outline-offset);
-  padding-block: 0.5rem;
-  padding-inline: 0.5rem;
+
+  // TODO Check if these paddings are necessary
+  padding-block: var(--amsterdam-search-field-button-padding-block);
+  padding-inline: var(--amsterdam-search-field-button-padding-inline);
   touch-action: manipulation;
 
   &:hover {

diff --git a/packages/css/src/components/skip-link/skip-link.scss b/packages/css/src/components/skip-link/skip-link.scss
@@ -12,8 +12,8 @@
   font-weight: var(--amsterdam-skip-link-font-weight);
   line-height: var(--amsterdam-skip-link-line-height);
   outline-offset: var(--amsterdam-skip-link-outline-offset);
-  padding-block: 0.5rem;
-  padding-inline: 1rem;
+  padding-block: var(--amsterdam-skip-link-padding-block);
+  padding-inline: var(--amsterdam-skip-link-padding-inline);
   text-align: center;
   text-decoration: none;
 

diff --git a/packages/css/src/components/table/table.scss b/packages/css/src/components/table/table.scss
@@ -25,8 +25,8 @@
 .amsterdam-table__cell,
 .amsterdam-table__header-cell {
   border-bottom: var(--amsterdam-table-cell-border-bottom);
-  padding-block: 1rem;
-  padding-inline: 1rem;
+  padding-block: var(--amsterdam-table-cell-padding-block);
+  padding-inline: var(--amsterdam-table-cell-padding-inline);
   text-align: start;
   vertical-align: top;
 }

diff --git a/packages/css/src/components/text-input/text-input.scss b/packages/css/src/components/text-input/text-input.scss
@@ -18,8 +18,8 @@
   font-weight: var(--amsterdam-text-input-font-weight);
   line-height: var(--amsterdam-text-input-line-height);
   outline-offset: var(--amsterdam-text-input-outline-offset);
-  padding-block: 0.5rem;
-  padding-inline: 1rem;
+  padding-block: var(--amsterdam-text-input-padding-block);
+  padding-inline: var(--amsterdam-text-input-padding-inline);
   touch-action: manipulation;
   width: 100%;
 

diff --git a/proprietary/tokens/src/brand/amsterdam/space.tokens.json b/proprietary/tokens/src/brand/amsterdam/space.tokens.json
@@ -8,7 +8,14 @@
         "comment": "Grows from 16px at 320px wide to 56px at 1600px wide."
       },
       "lg": { "value": "clamp(1.5rem, calc(4.6875vw + 0.5625rem), 5.25rem)" },
-      "xl": { "value": "clamp(2rem, calc(6.25vw + 0.75rem), 7rem)" }
+      "xl": { "value": "clamp(2rem, calc(6.25vw + 0.75rem), 7rem)" },
+      "inside": {
+        "xs": { "value": ".5rem" },
+        "sm": { "value": ".75rem" },
+        "md": { "value": "1rem" },
+        "lg": { "value": "1.5rem" },
+        "xl": { "value": "2rem" }
+      }
     }
   }
 }
diff --git a/proprietary/tokens/src/components/amsterdam/accordion.tokens.json b/proprietary/tokens/src/components/amsterdam/accordion.tokens.json
@@ -7,12 +7,18 @@
         "font-size": { "value": "{amsterdam.typography.text-level.5.font-size}" },
         "font-weight": { "value": "{amsterdam.typography.font-weight.bold}" },
         "line-height": { "value": "{amsterdam.typography.text-level.5.line-height}" },
+        "padding-block": { "value": "{amsterdam.space.inside.sm}" },
+        "padding-inline": { "value": "{amsterdam.space.inside.md}" },
         "focus": {
           "outline-offset": { "value": "{amsterdam.focus.outline-offset}" }
         },
         "hover": {
           "box-shadow": { "value": "inset 0 0 0 2px {amsterdam.color.neutral-grey3}" }
         }
+      },
+      "panel": {
+        "padding-block": { "value": "{amsterdam.space.inside.md}" },
+        "padding-inline": { "value": "{amsterdam.space.inside.md}" }
       }
     }
   }

diff --git a/proprietary/tokens/src/components/amsterdam/alert.tokens.json b/proprietary/tokens/src/components/amsterdam/alert.tokens.json
@@ -4,10 +4,10 @@
       "border-width": { "value": "4px" },
       "border-style": { "value": "solid" },
       "gap": { "value": "1rem" },
-      "padding-block-start": { "value": "1rem" },
-      "padding-block-end": { "value": "1rem" },
-      "padding-inline-start": { "value": "1.5rem" },
-      "padding-inline-end": { "value": "1.5rem" },
+      "padding-block-start": { "value": "{amsterdam.space.inside.md}" },
+      "padding-block-end": { "value": "{amsterdam.space.inside.md}" },
+      "padding-inline-start": { "value": "{amsterdam.space.inside.lg}" },
+      "padding-inline-end": { "value": "{amsterdam.space.inside.lg}" },
       "error": {
         "border-color": { "value": "{amsterdam.color.primary-red}" }
       },

diff --git a/proprietary/tokens/src/components/amsterdam/badge.tokens.json b/proprietary/tokens/src/components/amsterdam/badge.tokens.json
@@ -5,7 +5,7 @@
       "font-size": { "value": "{amsterdam.typography.text-level.5.font-size}" },
       "font-weight": { "value": "{amsterdam.typography.font-weight.bold}" },
       "line-height": { "value": "{amsterdam.typography.text-level.5.line-height}" },
-      "padding-inline": { "value": "0.5rem" },
+      "padding-inline": { "value": "{amsterdam.space.inside.xs}" },
       "blue": {
         "background-color": { "value": "{amsterdam.color.blue}" },
         "color": { "value": "{amsterdam.color.primary-black}" }

diff --git a/proprietary/tokens/src/components/amsterdam/button.tokens.json b/proprietary/tokens/src/components/amsterdam/button.tokens.json
@@ -6,10 +6,10 @@
       "font-size": { "value": "{amsterdam.typography.text-level.5.font-size}" },
       "line-height": { "value": "{amsterdam.typography.text-level.5.line-height}" },
       "gap": { "value": "1rem" },
-      "padding-inline-start": { "value": "1rem" },
-      "padding-inline-end": { "value": "1rem" },
-      "padding-block-start": { "value": "0.5rem" },
-      "padding-block-end": { "value": "0.5rem" },
+      "padding-block-start": { "value": "{amsterdam.space.inside.xs}" },
+      "padding-block-end": { "value": "{amsterdam.space.inside.xs}" },
+      "padding-inline-start": { "value": "{amsterdam.space.inside.md}" },
+      "padding-inline-end": { "value": "{amsterdam.space.inside.md}" },
       "outline-offset": { "value": "{amsterdam.focus.outline-offset}" },
       "busy": {
         "cursor": { "value": "{amsterdam.action.busy.cursor}" }

diff --git a/proprietary/tokens/src/components/amsterdam/header.tokens.json b/proprietary/tokens/src/components/amsterdam/header.tokens.json
@@ -4,7 +4,8 @@
       "column-gap": {
         "value": "{amsterdam.space.md}",
         "comment": "Must have the same value as `amsterdam.grid.column-gap`."
-      }
+      },
+      "padding-block": { "value": "{amsterdam.space.inside.md}" }
     }
   }
 }
diff --git a/proprietary/tokens/src/components/amsterdam/pagination.tokens.json b/proprietary/tokens/src/components/amsterdam/pagination.tokens.json
@@ -8,6 +8,7 @@
       "line-height": { "value": "{amsterdam.typography.text-level.5.line-height}" },
       "button": {
         "outline-offset": { "value": "{amsterdam.focus.outline-offset}" },
+        "padding-inline": { "value": "{amsterdam.space.inside.sm}" },
         "text-decoration-line": { "value": "{amsterdam.link-appearance.subtle.text-decoration-line}" },
         "text-decoration-thickness": { "value": "{amsterdam.link-appearance.text-decoration-thickness}" },
         "text-underline-offset": { "value": "{amsterdam.link-appearance.text-underline-offset}" },

diff --git a/proprietary/tokens/src/components/amsterdam/search-field.tokens.json b/proprietary/tokens/src/components/amsterdam/search-field.tokens.json
@@ -7,7 +7,9 @@
         "outline-offset": { "value": "{amsterdam.focus.outline-offset}" },
         "hover": {
           "background-color": { "value": "{amsterdam.color.dark-blue}" }
-        }
+        },
+        "padding-block": { "value": "{amsterdam.space.inside.xs}" },
+        "padding-inline": { "value": "{amsterdam.space.inside.xs}" }
       },
       "input": {
         "box-shadow": {
@@ -19,6 +21,8 @@
         "font-weight": { "value": "{amsterdam.typography.font-weight.normal}" },
         "line-height": { "value": "{amsterdam.typography.text-level.6.line-height}" },
         "outline-offset": { "value": "{amsterdam.focus.outline-offset}" },
+        "padding-block": { "value": "{amsterdam.space.inside.xs}" },
+        "padding-inline": { "value": "{amsterdam.space.inside.md}" },
         "cancel-button": {
           "background-image": {
             "value": "url(\"data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'><path fill='%23004699' fill-rule='evenodd' d='M29.333 5.47 26.53 2.668 16 13.187 5.47 2.666 2.668 5.47 13.187 16 2.666 26.53l2.804 2.803L16 18.813l10.53 10.52 2.803-2.804L18.813 16z'/></svg>\")"

diff --git a/proprietary/tokens/src/components/amsterdam/skip-link.tokens.json b/proprietary/tokens/src/components/amsterdam/skip-link.tokens.json
@@ -8,6 +8,8 @@
       "font-size": { "value": "{amsterdam.typography.text-level.6.font-size}" },
       "line-height": { "value": "{amsterdam.typography.text-level.6.line-height}" },
       "outline-offset": { "value": "{amsterdam.focus.outline-offset}" },
+      "padding-block": { "value": "{amsterdam.space.inside.xs}" },
+      "padding-inline": { "value": "{amsterdam.space.inside.md}" },
       "hover": {
         "background-color": { "value": "{amsterdam.color.dark-blue}" }
       }

diff --git a/proprietary/tokens/src/components/amsterdam/table.tokens.json b/proprietary/tokens/src/components/amsterdam/table.tokens.json
@@ -10,7 +10,9 @@
         "font-weight": { "value": "{amsterdam.typography.font-weight.bold}" }
       },
       "cell": {
-        "border-bottom": { "value": "1px solid {amsterdam.color.neutral-grey1}" }
+        "border-bottom": { "value": "1px solid {amsterdam.color.neutral-grey1}" },
+        "padding-block": { "value": "{amsterdam.space.inside.md}" },
+        "padding-inline": { "value": "{amsterdam.space.inside.md}" }
       },
       "header-cell": {
         "font-weight": { "value": "{amsterdam.typography.font-weight.bold}" }

diff --git a/proprietary/tokens/src/components/amsterdam/text-input.tokens.json b/proprietary/tokens/src/components/amsterdam/text-input.tokens.json
@@ -8,6 +8,8 @@
       "font-weight": { "value": "{amsterdam.typography.font-weight.normal}" },
       "line-height": { "value": "{amsterdam.typography.text-level.6.line-height}" },
       "outline-offset": { "value": "{amsterdam.focus.outline-offset}" },
+      "padding-block": { "value": "{amsterdam.space.inside.xs}" },
+      "padding-inline": { "value": "{amsterdam.space.inside.md}" },
       "disabled": {
         "background-color": { "value": "{amsterdam.color.primary-white}" },
         "box-shadow": { "value": "inset 0 0 0 1px {amsterdam.color.neutral-grey2}" },

diff --git a/storybook/src/docs/space.docs.mdx b/storybook/src/docs/space.docs.mdx
@@ -4,37 +4,71 @@ import { Meta } from "@storybook/blocks";
 
 # Space
 
-## Between components
+We distinguish 4 types of white space: Grid, Stack, Inside, and Type.
 
-Five sizes are available for white space between components.
-They are fluid and depend on the width of the window.
+## Grid Space
 
-The medium size is the default.
-Multiplication factors for the smaller and larger lengths are ¼, ½, 1½, and 2.
+This type of space creates gaps between the columns and rows of the [Grid](/docs/components-layout-grid--docs).
+It visually separates the most significant sections of a page, which in turn highlights the boundaries of every individual section.
+Grid Space helps the user recognize the layout of the page and find what they are looking for.
+It implements the Law of Proximity, one of the [Gestalt Principles](https://www.interaction-design.org/literature/topics/gestalt-principles).
 
-The tables below show the resulting pixels widths at some reference widths.
+The width or height of this type of space is fluid, depending on the width of the window.
+Five options are available, of which the middle one is the default.
+Multiplication factors for the smaller and larger lengths are ¼, ½, 1½, and 2.
+The tables below show the resulting pixel widths at some reference widths.
 
 #### Spacious
 
-In spacious mode, the medium white space grows from 16 to 56 pixels between window widths of 320 and 1600.
+In Spacious Mode, the medium grid space grows from 16 to 56 pixels between window widths of 320 and 1600.
 
-| Window width | Extra small | Small | Medium | Large | Extra large |
-| :----------: | :---------: | :---: | :----: | :---: | :---------: |
-|     320      |      4      |   8   | **16** |  24   |     32      |
-|     576      |      6      |  12   | **24** |  36   |     48      |
-|     1088     |     10      |  20   | **40** |  60   |     80      |
-|     1600     |     14      |  28   | **56** |  84   |     102     |
+|                 |  320   |  576   |  1088  |  1600  |
+| --------------: | :----: | :----: | :----: | :----: |
+| **Extra small** |   4    |   6    |   10   |   14   |
+|       **Small** |   8    |   12   |   20   |   28   |
+|      **Medium** | **16** | **24** | **40** | **56** |
+|       **Large** |   24   |   36   |   60   |   84   |
+| **Extra large** |   32   |   48   |   80   |  102   |
 
 #### Compact
 
-In compact mode, the medium white space grows from 16 to 40 pixels between window widths of 1088 and 2624.
+In Compact Mode, the medium grid space grows from 16 to 40 pixels between window widths of 1088 and 2624.
+
+|                 |   1088 |   1600 |   2112 |   2624 |
+| --------------: | -----: | -----: | -----: | -----: |
+| **Extra small** |      4 |      6 |      8 |     10 |
+|       **Small** |      8 |     12 |     16 |     20 |
+|      **Medium** | **16** | **24** | **32** | **40** |
+|       **Large** |     24 |     36 |     48 |     60 |
+| **Extra large** |     32 |     48 |     64 |     80 |
+
+## Stack Space
+
+This is the space between sets of components, for example between a list of cards, or next to an image.
+It is also used for combinations of components, like an icon accompanying a text, or a row of buttons.
+
+More information on this type of space will follow.
+
+## Inside Space
+
+This is the space at the four edges of a component: at the top, bottom, start, and end of its containing box.
+It is used for buttons and input fields, and for larger components with a coloured background or border.
+
+The medium size is 16 pixels wide in both Spacious and Compact Mode.
+
+|                 | Width |
+| --------------: | ----: |
+| **Extra small** |     8 |
+|       **Small** |    12 |
+|      **Medium** |    16 |
+|       **Large** |    24 |
+| **Extra large** |    32 |
+
+## Type Space
+
+This is the vertical space between text components like headings, paragraphs, and lists.
 
-| Window width | Extra small | Small | Medium | Large | Extra large |
-| :----------: | :---------: | :---: | :----: | :---: | :---------: |
-|     1088     |      4      |   8   | **16** |  24   |     32      |
-|     1600     |      6      |  12   | **24** |  36   |     48      |
-|     2112     |      8      |  16   | **32** |  48   |     64      |
-|     2624     |     10      |  20   | **40** |  60   |     80      |
+More information on this type of space will follow.
 
 ## About the units we use