Skip to content

Commit faf3dc6

Browse files
chazdeanlaurkim
chazdean
and
laurkim
authored
Update Box component docs and guidance (#7594)
<!-- ☝️How to write a good PR title: - Prefix it with [ComponentName] (if applicable), for example: [Button] - Start with a verb, for example: Add, Delete, Improve, Fix… - Give as much context as necessary and as little as possible - Prefix it with [WIP] while it’s a work in progress --> ### WHY are these changes introduced? ⚠️There still needs to be a solution for the use of the colour purple for the `Padding` example as shown in the [Figma](https://www.figma.com/file/5oEi1wm73KhGLN0VS02oYm/Layout-components?node-id=2764%3A33844) guide⚠️ <details> <summary>Padding Example Alternative 1</summary> <img src="https://user-images.githubusercontent.com/59836805/200398714-fffc2484-0a17-4fa9-857f-a7aecdcc5fa1.png" alt="example1" width="600"> </details> <details> <summary>Padding Example Alternative 2</summary> <img src="https://user-images.githubusercontent.com/59836805/200398744-f62cf05f-197d-491b-b240-452de462aa65.png" alt="example2" width="600"> </details> Fixes #6902 <!-- link to issue if one exists --> <!-- Context about the problem that’s being addressed. --> ### WHAT is this pull request doing? Updates the `Box` component docs and guidance <details> <summary>Box style guide</summary> <img src="https://user-images.githubusercontent.com/59836805/199257334-8cf55a79-995d-458a-8d4f-139a27ad9925.gif" alt="Box styleguide" width="600"> </details> <!-- Summary of the changes committed. Before / after screenshots are appreciated for UI changes. Make sure to include alt text that describes the screenshot. If you include an animated gif showing your change, wrapping it in a details tag is recommended. Gifs usually autoplay, which can cause accessibility issues for people reviewing your PR: <details> <summary>Summary of your gif(s)</summary> <img src="..." alt="Description of what the gif shows"> </details> --> <!-- ℹ️ Delete the following for small / trivial changes --> ### 🎩 checklist - [ ] Tested on [mobile](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting.md#cross-browser-testing) - [ ] Tested on [multiple browsers](https://help.shopify.com/en/manual/shopify-admin/supported-browsers) - [ ] Tested for [accessibility](https://github.com/Shopify/polaris/blob/main/documentation/Accessibility%20testing.md) - [ ] Updated the component's `README.md` with documentation changes - [ ] [Tophatted documentation](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting%20documentation.md) changes in the style guide Co-authored-by: Lo Kim <[email protected]>
1 parent 566dc20 commit faf3dc6

File tree

9 files changed

+228
-166
lines changed

9 files changed

+228
-166
lines changed

‎.changeset/shiny-mangos-tease.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'polaris.shopify.com': patch
3+
---
4+
5+
Updated `Box` component guidance and examples

‎polaris.shopify.com/content/components/box.md‎

Lines changed: 23 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,39 @@
11
---
22
title: Box
3-
description: Box is the most primitive layout component. Box has a set of padding options. Use it to render an individual item.
3+
description: Box is the most primitive layout component. It’s a way to access Polaris design tokens.
44
category: Structure
55
keywords:
66
- layout
77
status:
88
value: Alpha
99
message: This component is in development. There could be breaking changes made to it in a non-major release of Polaris. Please use with caution.
1010
examples:
11-
- fileName: box-with-padding.tsx
12-
title: Padding
11+
- fileName: box-default.tsx
12+
title: Default
13+
description: >-
14+
By default, box has no padding, borders, border radius, background, or shadows.
15+
- fileName: box-with-color.tsx
16+
title: Color
17+
description: >-
18+
Background color of box and text color inside a box can be adjusted using the [Color tokens](https://polaris.shopify.com/tokens/colors).
19+
- fileName: box-with-border.tsx
20+
title: Border
1321
description: >-
14-
Spacing inside Box can be set with the padding properties. Padding options are provided using our spacing tokens. There are 5 different padding properties: padding, paddingLeft, paddingRight, paddingTop, and paddingBottom.
22+
Border width can be adjusted using the [Shape tokens](https://polaris.shopify.com/tokens/shape), and a subset of tokens allows different types of border.
1523
- fileName: box-with-border-radius.tsx
1624
title: Border radius
1725
description: >-
18-
Border radius can be set with the border radius properties. Border radius options are provided using our shape tokens. There are 5 different padding properties: borderRadius, borderRadiusLeft, borderRadiusRight, borderRadiusTop, and borderRadiusBottom.
19-
- fileName: box-with-background.tsx
20-
title: Background
26+
Border radius can be adjusted using the [Shape tokens](https://polaris.shopify.com/tokens/shape).
27+
- fileName: box-with-padding.tsx
28+
title: Padding
2129
description: >-
22-
Background color for Box can be set with the background prop. Background color options are provided using our color tokens that relate to background, surface, backdrop, and overlay.
23-
- fileName: box-with-border.tsx
24-
title: Border
30+
Padding can be added to either all sides, left, right, top, and bottom, using the [Spacing tokens](https://polaris.shopify.com/tokens/spacing).
31+
- fileName: box-with-shadow.tsx
32+
title: Shadow
2533
description: >-
26-
Border color for Box can be set with the border prop. Border color options are provided using our shape tokens.
34+
Shadow can be applied using the Shadow token. The base is [--p-shadow-base](https://polaris.shopify.com/tokens/depth).
2735
---
36+
37+
## Related components
38+
39+
- For more specific use cases, [use the Card](https://polaris.shopify.com/components/card) component.

‎polaris.shopify.com/pages/examples/box-default.tsx‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
import React from 'react';
2+
import {Box, Text} from '@shopify/polaris';
3+
4+
import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
5+
6+
function BoxDefaultExample() {
7+
return (
8+
<Box>
9+
<Placeholder label="Content inside a box" />
10+
</Box>
11+
);
12+
}
13+
14+
const Placeholder = ({label = '', height = 'auto', width = 'auto'}) => {
15+
return (
16+
<div
17+
style={{
18+
background: '#7B47F1',
19+
height: height,
20+
width: width,
21+
}}
22+
>
23+
<div
24+
style={{
25+
color: '#FFFFFF',
26+
}}
27+
>
28+
<Text as="h2" variant="bodyMd" fontWeight="medium">
29+
{label}
30+
</Text>
31+
</div>
32+
</div>
33+
);
34+
};
35+
36+
export default withPolarisExample(BoxDefaultExample);

‎polaris.shopify.com/pages/examples/box-with-background.tsx‎

Lines changed: 0 additions & 33 deletions
This file was deleted.

‎polaris.shopify.com/pages/examples/box-with-border-radius.tsx‎

Lines changed: 26 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,47 +1,37 @@
11
import React from 'react';
2-
import {Box, Stack, Text} from '@shopify/polaris';
2+
import {Box, Text} from '@shopify/polaris';
33

44
import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
55

66
function BoxWithBorderRadiusExample() {
77
return (
8-
<Stack vertical>
9-
<Box
10-
background="surface"
11-
border="base"
12-
borderRadius="2"
13-
padding="5"
14-
shadow="card"
15-
>
16-
<Text as="h2" variant="headingMd">
17-
Box with uniform border radius
18-
</Text>
19-
</Box>
20-
<Box
21-
background="surface"
22-
border="base"
23-
borderRadiusEndStart="2"
24-
borderRadiusEndEnd="2"
25-
padding="5"
26-
shadow="card"
27-
>
28-
<Text as="h2" variant="headingMd">
29-
Box with bottom border radius
30-
</Text>
31-
</Box>
32-
<Box
33-
background="surface"
34-
border="base"
35-
borderRadius="base"
36-
padding="5"
37-
shadow="card"
8+
<Box background="surface" borderRadius="2">
9+
<Placeholder label="Content inside a box" />
10+
</Box>
11+
);
12+
}
13+
14+
const Placeholder = ({label = '', height = 'auto', width = 'auto'}) => {
15+
return (
16+
<div
17+
style={{
18+
background: '#7B47F1',
19+
height: height,
20+
width: width,
21+
borderRadius: 'inherit',
22+
}}
23+
>
24+
<div
25+
style={{
26+
color: '#FFFFFF',
27+
}}
3828
>
39-
<Text as="h2" variant="headingMd">
40-
Box with border radius base
29+
<Text as="h2" variant="bodyMd" fontWeight="medium">
30+
{label}
4131
</Text>
42-
</Box>
43-
</Stack>
32+
</div>
33+
</div>
4434
);
45-
}
35+
};
4636

4737
export default withPolarisExample(BoxWithBorderRadiusExample);

‎polaris.shopify.com/pages/examples/box-with-border.tsx‎

Lines changed: 25 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -1,68 +1,36 @@
11
import React from 'react';
2-
import {Box, Stack, Text} from '@shopify/polaris';
2+
import {Box, Text} from '@shopify/polaris';
33

44
import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
55

66
function BoxWithBorderExample() {
77
return (
8-
<Stack vertical>
9-
<Box
10-
background="surface"
11-
border="base"
12-
borderRadius="2"
13-
padding="5"
14-
shadow="card"
15-
>
16-
<Text as="h2" variant="headingMd">
17-
Box with border base
18-
</Text>
19-
</Box>
20-
<Box
21-
background="surface"
22-
border="divider"
23-
borderRadius="2"
24-
padding="5"
25-
shadow="card"
26-
>
27-
<Text as="h2" variant="headingMd">
28-
Box with border divider
29-
</Text>
30-
</Box>
31-
<Box
32-
background="surface"
33-
border="dark"
34-
borderRadius="2"
35-
padding="5"
36-
shadow="card"
37-
>
38-
<Text as="h2" variant="headingMd">
39-
Box with border dark
40-
</Text>
41-
</Box>
42-
<Box
43-
background="surface"
44-
border="transparent"
45-
borderRadius="2"
46-
padding="5"
47-
shadow="card"
48-
>
49-
<Text as="h2" variant="headingMd">
50-
Box with border transparent
51-
</Text>
52-
</Box>
53-
<Box
54-
background="surface"
55-
border="divider-on-dark"
56-
borderRadius="2"
57-
padding="5"
58-
shadow="card"
8+
<Box border="dark">
9+
<Placeholder label="Content inside a box" />
10+
</Box>
11+
);
12+
}
13+
14+
const Placeholder = ({label = '', height = 'auto', width = 'auto'}) => {
15+
return (
16+
<div
17+
style={{
18+
background: '#F4E8FD',
19+
height: height,
20+
width: width,
21+
}}
22+
>
23+
<div
24+
style={{
25+
color: '#26282C',
26+
}}
5927
>
60-
<Text as="h2" variant="headingMd">
61-
Box with border divider on dark
28+
<Text as="h2" variant="bodyMd" fontWeight="medium">
29+
{label}
6230
</Text>
63-
</Box>
64-
</Stack>
31+
</div>
32+
</div>
6533
);
66-
}
34+
};
6735

6836
export default withPolarisExample(BoxWithBorderExample);

‎polaris.shopify.com/pages/examples/box-with-color.tsx‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
import React from 'react';
2+
import {Box, Text} from '@shopify/polaris';
3+
4+
import {withPolarisExample} from '../../src/components/PolarisExampleWrapper';
5+
6+
function BoxWithColorExample() {
7+
return (
8+
<Box background="surface-success">
9+
<Text as="h2" variant="bodyMd" fontWeight="medium">
10+
Content inside a box
11+
</Text>
12+
</Box>
13+
);
14+
}
15+
16+
export default withPolarisExample(BoxWithColorExample);

0 commit comments

Comments
 (0)