Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: Add documention for Gap and Margin utility classes #1427

Merged
merged 30 commits into from
Jul 24, 2024
Merged
Show file tree
Hide file tree
Changes from 21 commits
Commits
Show all changes
30 commits
Select commit Hold shift + click to select a range
296bbbb
Add documentation for the Margin Bottom utility class
VincentSmedinga Jul 19, 2024
38cc30f
Restore not rendering medium gap classes for Row and Column
VincentSmedinga Jul 19, 2024
c69d6c7
Add documentation for the Gap utility class
VincentSmedinga Jul 19, 2024
cb0f1c5
Use Paragraph components in example code
VincentSmedinga Jul 22, 2024
6b1981b
Import from source in stories
VincentSmedinga Jul 22, 2024
9ff747f
Finetune documentation
VincentSmedinga Jul 22, 2024
b8a7a90
Merge branch 'develop' into feature/DES-847-utility-class-docs
VincentSmedinga Jul 22, 2024
52cbcab
Finetune documentation
VincentSmedinga Jul 22, 2024
3a5e9c6
Suggest Gap utility next to Column component
VincentSmedinga Jul 23, 2024
b90084e
Only import the Story’s component from source
VincentSmedinga Jul 23, 2024
453ad5c
Reconnect sentences in Visually Hidden docs
VincentSmedinga Jul 23, 2024
c5d6a04
Remove unnecessary wrapper elements from examples
VincentSmedinga Jul 23, 2024
f7d5e0f
Expand content of ‘Foundation’ and ‘Utilities’ in sidebar
VincentSmedinga Jul 22, 2024
0857e89
Merge branch 'develop' into feature/DES-847-utility-class-docs
VincentSmedinga Jul 23, 2024
25e406b
Display class names and a preview
VincentSmedinga Jul 23, 2024
02da819
Make token preview for border consistent
VincentSmedinga Jul 23, 2024
ab92532
Fix previews of margin length
VincentSmedinga Jul 23, 2024
ea1bcdd
Add token previews to space tables
VincentSmedinga Jul 23, 2024
b626fee
Remove full stop from HTML class names
VincentSmedinga Jul 23, 2024
9deeb96
Reuse length options in arg types
VincentSmedinga Jul 24, 2024
fc27fe9
Merge branch 'develop' into feature/DES-847-utility-class-docs
VincentSmedinga Jul 24, 2024
fe059e4
Move Gap component to separate file
alimpens Jul 24, 2024
065de00
Add keys to elements in an array
VincentSmedinga Jul 24, 2024
602b7a5
Move Margin and VisuallyHidden component to separate file
VincentSmedinga Jul 24, 2024
a1a1376
Improve types for Storybook components
VincentSmedinga Jul 24, 2024
7cfee6c
Simplify props and add missing type import
VincentSmedinga Jul 24, 2024
03208bc
Add fragments to story render functions as they can’t return an array
VincentSmedinga Jul 24, 2024
859eb7f
Use `size` instead of `length`
VincentSmedinga Jul 24, 2024
4364153
Remove stray `key`
VincentSmedinga Jul 24, 2024
58a69b2
Merge branch 'develop' into feature/DES-847-utility-class-docs
VincentSmedinga Jul 24, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion packages/css/src/common/size.scss
VincentSmedinga marked this conversation as resolved.
Show resolved Hide resolved
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,12 @@
* Copyright Gemeente Amsterdam
alimpens marked this conversation as resolved.
Show resolved Hide resolved
*/

/** The set of available options for sizing. */
/** The set of available widths for gaps and margins. */
$ams-sizes: (
"no": "none",
"xs": "extra-small",
"sm": "small",
"md": "medium",
"lg": "large",
"xl": "extra-large",
);
6 changes: 4 additions & 2 deletions packages/css/src/components/column/column.scss
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,9 @@
}

@each $size, $label in $ams-sizes {
.ams-column--gap-#{$label} {
gap: var(--ams-column-gap-#{$size});
@if $size != "md" {
.ams-column--gap-#{$label} {
gap: var(--ams-column-gap-#{$size});
}
}
}
23 changes: 22 additions & 1 deletion packages/css/src/components/gap/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,25 @@

# Gap

Use these utility classes to add consistent white space between a set of elements.
Adds white space between a set of elements.

## Class names

The five sizes of [Component Space](/docs/foundation-design-tokens-space--docs) are available for the length of the margin.

| Class name | Preview |
| ------------- | ----------------------------------------------------------------------------------------- |
| `ams-gap--xs` | <div className="ams-docs-token-preview--space" style="inline-size: var(--ams-gap-xs);" /> |
| `ams-gap--sm` | <div className="ams-docs-token-preview--space" style="inline-size: var(--ams-gap-sm);" /> |
| `ams-gap--md` | <div className="ams-docs-token-preview--space" style="inline-size: var(--ams-gap-md);" /> |
| `ams-gap--lg` | <div className="ams-docs-token-preview--space" style="inline-size: var(--ams-gap-lg);" /> |
| `ams-gap--xl` | <div className="ams-docs-token-preview--space" style="inline-size: var(--ams-gap-xl);" /> |

## Guidelines

- Use this utility class to vertically separate the children of a parent element from each other.
- It can be used on any element and sets the `gap` CSS property.
It also makes the element a grid container; the gap would be ignored otherwise.
These declarations are marked with the `!important` flag to ensure they override any other gaps and display modes.
- To add a gap between 2 siblings, the first one can be given a [Margin Bottom](/docs/utilities-css-margin--docs) instead.
This may be preferable because it doesn’t change the parent’s display mode.
6 changes: 4 additions & 2 deletions packages/css/src/components/gap/gap.scss
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,9 @@
}

@each $size in map-keys($ams-sizes) {
.ams-gap--#{$size} {
gap: var(--ams-gap-#{$size}) !important;
@if $size != "no" {
.ams-gap--#{$size} {
grid-gap: var(--ams-gap-#{$size}) !important;
}
}
}
22 changes: 21 additions & 1 deletion packages/css/src/components/margin/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,24 @@

# Margin

Use these utility classes to add white space below a single element.
Adds white space below a single element.

## Class names

The five sizes of [Component Space](/docs/foundation-design-tokens-space--docs) are available for the length of the margin.

| Class name | Preview |
| ------------ | -------------------------------------------------------------------------------------------- |
| `ams-mb--xs` | <div className="ams-docs-token-preview--space" style="inline-size: var(--ams-margin-xs);" /> |
| `ams-mb--sm` | <div className="ams-docs-token-preview--space" style="inline-size: var(--ams-margin-sm);" /> |
| `ams-mb--md` | <div className="ams-docs-token-preview--space" style="inline-size: var(--ams-margin-md);" /> |
| `ams-mb--lg` | <div className="ams-docs-token-preview--space" style="inline-size: var(--ams-margin-lg);" /> |
| `ams-mb--xl` | <div className="ams-docs-token-preview--space" style="inline-size: var(--ams-margin-xl);" /> |

## Guidelines

- Use this utility class to vertically separate one element from the next.
- It can be used on any element and sets the `margin-block-end` CSS property. This declaration is marked with the `!important` flag to ensure it overrides any other margins.
- Elements’ top and bottom margins are sometimes collapsed into a single margin. Consult [MDN](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_box_model/Mastering_margin_collapsing) for details.
- To add equal margins between elements, either use the [Gap](/docs/utilities-css-gap--docs) utility class on their common parent or wrap them in a [Column](/docs/components-layout-column--docs) component.
This helps in loops: it prevents having to treat the last element differently.
6 changes: 4 additions & 2 deletions packages/css/src/components/margin/margin.scss
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,9 @@
@import "../../common/size";

@each $size in map-keys($ams-sizes) {
.ams-mb--#{$size} {
margin-block-end: var(--ams-margin-#{$size}) !important;
@if $size != "no" {
.ams-mb--#{$size} {
margin-block-end: var(--ams-margin-#{$size}) !important;
}
}
}
6 changes: 4 additions & 2 deletions packages/css/src/components/row/row.scss
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,10 @@
}

@each $size, $label in $ams-sizes {
.ams-row--gap-#{$label} {
gap: var(--ams-row-gap-#{$size});
@if $size != "md" {
.ams-row--gap-#{$label} {
gap: var(--ams-row-gap-#{$size});
}
}
}

Expand Down
6 changes: 5 additions & 1 deletion packages/css/src/components/visually-hidden/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,11 @@

Hides content from sighted users but keeps it accessible to non-visual user agents, such as screen readers.

## Class name

`ams-visually-hidden`

## Guidelines

- In most cases, visually available content should be accessible to non-visual user agents and vice versa.
- Elaborate instructions or guidance read only by non-visual user agents can do more harm than good.
Elaborate instructions or guidance read only by non-visual user agents can do more harm than good.
2 changes: 1 addition & 1 deletion storybook/config/manager-head.html
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
// Somewhat hacky way to expand all folders. Storybook does not support that natively.
var clickCollapsedItemsUntilNoneLeft = () => {
const collapsedItems = document.querySelectorAll(
':is(button[data-parent-id="components"], button[data-parent-id="pages"])[aria-expanded="false"]',
':is(button[data-parent-id="foundation"], button[data-parent-id="components"], button[data-parent-id="utilities"], button[data-parent-id="pages"])[aria-expanded="false"]',
);

for (item of collapsedItems) {
Expand Down
13 changes: 13 additions & 0 deletions storybook/config/preview-body.html
Original file line number Diff line number Diff line change
Expand Up @@ -59,4 +59,17 @@
margin: -1rem; /* stylelint-disable-line */
padding: 1rem; /* stylelint-disable-line */
}

[class*="ams-docs-token-preview--"] {
block-size: 1rem;
}

[class*="ams-docs-token-preview--border"] {
border-inline-start-style: solid;
}

[class*="ams-docs-token-preview--space"] {
outline: 1px dashed var(--ams-color-neutral-grey2);
background-color: var(--ams-color-primary-white);
}
</style>
3 changes: 2 additions & 1 deletion storybook/src/components/Accordion/Accordion.stories.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@
* Copyright Gemeente Amsterdam
*/

import { Accordion, Paragraph } from '@amsterdam/design-system-react/src'
import { Paragraph } from '@amsterdam/design-system-react'
import { Accordion } from '@amsterdam/design-system-react/src'
import { Meta, StoryObj } from '@storybook/react'
import { exampleAccordionHeading, exampleParagraph } from '../shared/exampleContent'

Expand Down
3 changes: 2 additions & 1 deletion storybook/src/components/Alert/Alert.stories.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@
* Copyright Gemeente Amsterdam
*/

import { Alert, Link, Paragraph, UnorderedList } from '@amsterdam/design-system-react/src'
import { Link, Paragraph, UnorderedList } from '@amsterdam/design-system-react'
import { Alert } from '@amsterdam/design-system-react/src'
import { Meta, StoryObj } from '@storybook/react'

const meta = {
Expand Down
3 changes: 2 additions & 1 deletion storybook/src/components/AspectRatio/AspectRatio.stories.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@
* Copyright Gemeente Amsterdam
*/

import { AspectRatio, Image } from '@amsterdam/design-system-react/src'
import { Image } from '@amsterdam/design-system-react'
import { AspectRatio } from '@amsterdam/design-system-react/src'
import { Meta, StoryObj } from '@storybook/react'

const meta = {
Expand Down
3 changes: 2 additions & 1 deletion storybook/src/components/Avatar/Avatar.stories.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@
* Copyright Gemeente Amsterdam
*/

import { Avatar, Header, PageMenu } from '@amsterdam/design-system-react/src'
import { Header, PageMenu } from '@amsterdam/design-system-react'
import { Avatar } from '@amsterdam/design-system-react/src'
import { SearchIcon } from '@amsterdam/design-system-react-icons'
import { Meta, StoryObj } from '@storybook/react'

Expand Down
3 changes: 2 additions & 1 deletion storybook/src/components/Button/Button.stories.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@
* Copyright Gemeente Amsterdam
*/

import { Button, Icon } from '@amsterdam/design-system-react/src'
import { Icon } from '@amsterdam/design-system-react'
import { Button } from '@amsterdam/design-system-react/src'
import { ShareIcon } from '@amsterdam/design-system-react-icons'
import { Meta, StoryObj } from '@storybook/react'

Expand Down
3 changes: 2 additions & 1 deletion storybook/src/components/Card/Card.stories.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@
* Copyright Gemeente Amsterdam
*/

import { AspectRatio, Card, Heading, Image, Paragraph } from '@amsterdam/design-system-react/src'
import { AspectRatio, Heading, Image, Paragraph } from '@amsterdam/design-system-react'
import { Card } from '@amsterdam/design-system-react/src'
import { Meta, StoryObj } from '@storybook/react'
import { exampleTopTask } from '../shared/exampleContent'

Expand Down
2 changes: 1 addition & 1 deletion storybook/src/components/Column/Column.docs.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ The five [space](/docs/foundation-design-tokens-space--docs) sizes are available

Wrap a Column around a set of components that need the same amount of white space between them.

To add white space below a single element, you can alternatively use a utility class for bottom margins, e.g. `class="ams-mb--md"`.
To add white space below a single element, the [Margin Bottom](/docs/utilities-css-margin--docs) utility class can be used as well.

## Examples

Expand Down
3 changes: 2 additions & 1 deletion storybook/src/components/Column/Column.stories.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@
* Copyright Gemeente Amsterdam
*/

import { Card, Column, Heading, Paragraph } from '@amsterdam/design-system-react/src'
import { Card, Heading, Paragraph } from '@amsterdam/design-system-react'
import { Column } from '@amsterdam/design-system-react/src'
import { Meta, StoryObj } from '@storybook/react'

const ThreeBoxes = Array.from(Array(3).keys()).map((i) => (
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
* Copyright Gemeente Amsterdam
*/

import { DescriptionList } from '@amsterdam/design-system-react'
import { DescriptionList } from '@amsterdam/design-system-react/src'
import { Meta, StoryObj } from '@storybook/react'
import { inverseColorDecorator } from '../shared/decorators'
import { exampleParagraph } from '../shared/exampleContent'
Expand Down
3 changes: 2 additions & 1 deletion storybook/src/components/Dialog/Dialog.stories.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@
* Copyright Gemeente Amsterdam
*/

import { Button, Dialog, Heading, Paragraph } from '@amsterdam/design-system-react/src'
import { Button, Heading, Paragraph } from '@amsterdam/design-system-react'
import { Dialog } from '@amsterdam/design-system-react/src'
import { Meta, StoryObj } from '@storybook/react'
import { MouseEvent } from 'react'

Expand Down
4 changes: 2 additions & 2 deletions storybook/src/components/Field/Field.stories.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,8 @@
* Copyright Gemeente Amsterdam
*/

import { ErrorMessage, Label, TextInput } from '@amsterdam/design-system-react'
import { Field, Paragraph } from '@amsterdam/design-system-react/src'
import { ErrorMessage, Label, Paragraph, TextInput } from '@amsterdam/design-system-react'
import { Field } from '@amsterdam/design-system-react/src'
import { Meta, StoryObj } from '@storybook/react'

const meta = {
Expand Down
4 changes: 2 additions & 2 deletions storybook/src/components/FieldSet/FieldSet.stories.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,12 @@ import {
Column,
ErrorMessage,
Field,
FieldSet,
Label,
Paragraph,
Radio,
TextInput,
} from '@amsterdam/design-system-react/src'
} from '@amsterdam/design-system-react'
import { FieldSet } from '@amsterdam/design-system-react/src'
import { Meta, StoryObj } from '@storybook/react'

const meta = {
Expand Down
3 changes: 2 additions & 1 deletion storybook/src/components/Footer/Footer.stories.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@
* Copyright Gemeente Amsterdam
*/

import { Footer, Grid, Heading, LinkList, PageMenu, Paragraph } from '@amsterdam/design-system-react/src'
import { Grid, Heading, LinkList, PageMenu, Paragraph } from '@amsterdam/design-system-react'
import { Footer } from '@amsterdam/design-system-react/src'
import {
CameraIcon,
ClockIcon,
Expand Down
3 changes: 2 additions & 1 deletion storybook/src/components/Grid/Grid.stories.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@
* Copyright Gemeente Amsterdam
*/

import { Grid, Screen } from '@amsterdam/design-system-react/src'
import { Screen } from '@amsterdam/design-system-react'
import { Grid } from '@amsterdam/design-system-react/src'
import type { GridCellProps } from '@amsterdam/design-system-react/src'
import { Meta, StoryObj } from '@storybook/react'

Expand Down
3 changes: 2 additions & 1 deletion storybook/src/components/Header/Header.stories.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@
* Copyright Gemeente Amsterdam
*/

import { Header, PageMenu } from '@amsterdam/design-system-react/src'
import { PageMenu } from '@amsterdam/design-system-react'
import { Header } from '@amsterdam/design-system-react/src'
import { SearchIcon } from '@amsterdam/design-system-react-icons'
import { Meta, StoryObj } from '@storybook/react'

Expand Down
3 changes: 2 additions & 1 deletion storybook/src/components/Heading/Heading.stories.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@
* Copyright Gemeente Amsterdam
*/

import { Column, Heading } from '@amsterdam/design-system-react/src'
import { Column } from '@amsterdam/design-system-react'
import { Heading } from '@amsterdam/design-system-react/src'
import { Meta, StoryObj } from '@storybook/react'
import { inverseColorDecorator } from '../shared/decorators'
import { exampleHeading } from '../shared/exampleContent'
Expand Down
3 changes: 2 additions & 1 deletion storybook/src/components/Icon/Icon.stories.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@
* Copyright Gemeente Amsterdam
*/

import { Heading, Icon } from '@amsterdam/design-system-react/src'
import { Heading } from '@amsterdam/design-system-react'
import { Icon } from '@amsterdam/design-system-react/src'
import * as Icons from '@amsterdam/design-system-react-icons'
import { Meta, StoryObj } from '@storybook/react'

Expand Down
3 changes: 2 additions & 1 deletion storybook/src/components/Link/Link.stories.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@
* Copyright Gemeente Amsterdam
*/

import { Link, Paragraph } from '@amsterdam/design-system-react/src'
import { Paragraph } from '@amsterdam/design-system-react'
import { Link } from '@amsterdam/design-system-react/src'
import type { Meta, StoryObj } from '@storybook/react'

type Story = StoryObj<typeof Link>
Expand Down
3 changes: 2 additions & 1 deletion storybook/src/components/Mark/Mark.stories.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@
* Copyright Gemeente Amsterdam
*/

import { Mark, Paragraph } from '@amsterdam/design-system-react/src'
import { Paragraph } from '@amsterdam/design-system-react'
import { Mark } from '@amsterdam/design-system-react/src'
import { Meta, StoryObj } from '@storybook/react'

const meta = {
Expand Down
3 changes: 2 additions & 1 deletion storybook/src/components/MegaMenu/MegaMenu.stories.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@
* Copyright Gemeente Amsterdam
*/

import { Grid, Heading, LinkList, MegaMenu, Screen } from '@amsterdam/design-system-react/src'
import { Grid, Heading, LinkList, Screen } from '@amsterdam/design-system-react'
import { MegaMenu } from '@amsterdam/design-system-react/src'
import { Meta, StoryObj } from '@storybook/react'

const meta = {
Expand Down
3 changes: 2 additions & 1 deletion storybook/src/components/OrderedList/OrderedList.stories.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@
* Copyright Gemeente Amsterdam
*/

import { Heading, OrderedList, Paragraph } from '@amsterdam/design-system-react/src'
import { Heading, Paragraph } from '@amsterdam/design-system-react'
import { OrderedList } from '@amsterdam/design-system-react/src'
import type { Meta, StoryObj } from '@storybook/react'
import { inverseColorDecorator } from '../shared/decorators'
import { exampleOrderedList } from '../shared/exampleContent'
Expand Down
3 changes: 2 additions & 1 deletion storybook/src/components/Overlap/Overlap.stories.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@
* Copyright Gemeente Amsterdam
*/

import { AspectRatio, Grid, Image, Overlap, SearchField } from '@amsterdam/design-system-react/src'
import { AspectRatio, Grid, Image, SearchField } from '@amsterdam/design-system-react'
import { Overlap } from '@amsterdam/design-system-react/src'
import { Meta, StoryObj } from '@storybook/react'

const meta = {
Expand Down
3 changes: 2 additions & 1 deletion storybook/src/components/Radio/Radio.stories.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@
* Copyright Gemeente Amsterdam
*/

import { FieldSet, Radio } from '@amsterdam/design-system-react/src'
import { FieldSet } from '@amsterdam/design-system-react'
import { Radio } from '@amsterdam/design-system-react/src'
import { useArgs } from '@storybook/preview-api'
import { Meta, StoryObj } from '@storybook/react'

Expand Down
3 changes: 2 additions & 1 deletion storybook/src/components/Row/Row.stories.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@
* Copyright Gemeente Amsterdam
*/

import { Avatar, Button, Heading, Link, Paragraph, Row } from '@amsterdam/design-system-react/src'
import { Avatar, Button, Heading, Link, Paragraph } from '@amsterdam/design-system-react'
import { Row } from '@amsterdam/design-system-react/src'
import { crossAlignOptions, mainAlignOptions } from '@amsterdam/design-system-react/src/common/layout'
import { Meta, StoryObj } from '@storybook/react'

Expand Down
Loading