Skip to content

Commit d65a68e

Browse files
dfmcpheedfmcphee
committed
Updating component readmes
1 parent 42afdc0 commit d65a68e

File tree

43 files changed

+4897
-525
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

43 files changed

+4897
-525
lines changed

‎src/components/AccountConnection/README.md‎

Lines changed: 113 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,39 +1,132 @@
11
---
2-
name: AccountConnection
2+
name: Account connection
33
tags:
4-
-
5-
category:
4+
- connect
5+
- disconnect
6+
- account
7+
- sign-up
8+
category: Actions
69
---
710

8-
# AccountConnection
11+
# Account connection
912

10-
AccountConnection description
13+
The account connection component is used so merchants can connect or disconnect
14+
their store to various accounts. For example, if merchants want to use the
15+
Facebook sales channel, they need to connect their Facebook
16+
account to their Shopify store.
1117

12-
_Not what you’re looking for?_
18+
**Problem**
1319

14-
Use this instead.
20+
Merchants need a way to authorize their third-party accounts to integrate with their Shopify store.
1521

16-
## Problem
22+
**Solution**
1723

18-
Problem description.
24+
The account component gives merchants a consistent and secure way to authorize their accounts and control permissions.
1925

20-
## Solution
26+
---
27+
28+
## Best practices
2129

22-
Solution description
30+
The account component should:
2331

24-
## API
25-
| Prop | Type | Default | Required |
26-
| --- | --- | --- | --- |
27-
| | | | |
32+
* Be placed at the top of the Account page for the relevant sales channel
33+
* Identify the name of the platform or service the merchant can connect to
34+
* Show whether the account is connected or disconnected so that merchants can easily connect or disconnect an account
35+
* Include a link to the relevant sales channel or platform terms and conditions,
36+
including information about any charges or fees that a merchant may incur by
37+
using the channel or platform
38+
* Link to terms and conditions, which should open up on the sales channel
39+
developer’s website in a new browser window
40+
41+
---
2842

2943
## Content guidelines
3044

31-
### Example type of content
32-
Guidelines for type of content
45+
### Heading
46+
47+
The account connection heading should state the name of the platform or service
48+
merchants will connect to, followed by the word “account”.
49+
50+
#### For example:
51+
52+
* Facebook account
53+
* Mailchimp account
54+
* Instagram account
55+
56+
<!-- usagelist -->
57+
58+
#### Do
59+
Facebook account
60+
61+
#### Don't
62+
Connect your Account
63+
64+
<!-- end -->
65+
66+
Headings should be written in sentence case.
67+
68+
<!-- usagelist -->
69+
70+
#### Do
71+
Instagram account
72+
73+
#### Don't
74+
Instagram Account
75+
76+
<!-- end -->
77+
78+
### Terms and conditions
79+
80+
Clearly link to your terms and conditions and let merchants know about any additional costs of your service.
81+
82+
<!-- usagelist -->
83+
84+
#### Do
85+
By clicking Connect, you agree to accept Sample’s terms and conditions.
86+
You’ll pay a commission rate of 15% on sales made through Sample.
87+
88+
#### Don't
89+
Learn about terms, conditions, and payment details.
90+
91+
<!-- end -->
92+
93+
### Connect button
94+
95+
Always use the verb Connect in the button of the account connection component. When merchants click or tap “Connect” it should open up your platform or service’s authorization page in a new browser window.
96+
97+
<!-- usagelist -->
98+
99+
#### Do
100+
Connect
101+
102+
#### Don't
103+
Connect to app
104+
105+
<!-- end -->
106+
107+
| Prop | Type | Description |
108+
| ---- | ---- | ----------- |
109+
| title | React.ReactNode | Element containing title |
110+
| details | React.ReactNode | Element containing details |
111+
| termsOfService | React.ReactNode | Element containing terms of service |
112+
| accountName | string | The name of the service |
113+
| avatarUrl | string | URL for the user’s avatar image |
114+
| connected | boolean | Set if the account is connected |
115+
| action | Action | Action for account connection |
33116

34117
## Examples
35118

36-
### Basic example
37-
Basic example description
119+
### Default account connection component
120+
121+
Use to let merchants connect or disconnect their store to their third-party accounts (e.g. Facebook).
38122

39-
Basic example code block
123+
```jsx
124+
<AccountConnection
125+
title="Example App"
126+
action={{
127+
content: 'Connect'
128+
}}
129+
details="No account connected"
130+
termsOfService={<p>By clicking Connect, you agree to accept Sample App’s <Link url="Example App">Terms and conditions</Link>. You’ll pay a commission rate of 15% on sales made through Example App.</p>}
131+
/>
132+
```

‎src/components/ActionList/README.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
---
2+
name: Action list
3+
tags:
4+
- actions
5+
- list
6+
- select
7+
- options
8+
category: Actions
9+
---
10+
11+
# Action list
12+
13+
Action lists render a list of actions or selectable options. This component is usually placed inside a [popover container](/components/overlays/popover) to create a dropdown menu or to let merchants select from a list of options.
14+
15+
**Problem**
16+
17+
There are lots of different paths a merchant can take. Listing them all out in the interface would make the experience feel overwhelming and cluttered.
18+
19+
**Solution**
20+
21+
Action lists in popovers let merchants expose additional information and actions when they’re ready to explore them.
22+
23+
>**Not what you’re looking for?**
24+
>* To combine more than one button in a single layout,
25+
[use the button group component](/components/actions/button-group).
26+
>* To display a list of related content, [use the list component](/components/tables-and-lists/list).
27+
28+
---
29+
30+
## Best practices
31+
32+
Actions lists should:
33+
34+
* Be used for secondary or less important information and actions since they’re hidden until the merchant exposes them by opening a popover
35+
* Contain actions that share a relationships to each other
36+
37+
---
38+
39+
## Content guidelines
40+
41+
### Action lists
42+
43+
Each item in an action list should be clear and predictable. Merchants should be able to anticipate what will
44+
happen when they click on an action item.
45+
46+
<!-- usagelist -->
47+
48+
#### Do
49+
Buy shipping label
50+
51+
#### Don't
52+
Buy
53+
54+
<!-- end -->
55+
56+
Each item in an action list should always lead with a strong verb that encourages action. To provide enough context use the {verb}+{noun} format unless the action is clear with a single verb.
57+
58+
<!-- usagelist -->
59+
60+
#### Do
61+
- Rename
62+
- Edit HTML
63+
64+
#### Don't
65+
- File name changes
66+
- HTML editing options
67+
68+
<!-- end -->
69+
70+
Each item in an action list should be scannable avoiding unnecessary words and articles such as the, an, or a.
71+
72+
<!-- usagelist -->
73+
74+
#### Do
75+
- Add menu item
76+
77+
#### Don't
78+
- Add a menu item
79+
80+
<!-- end -->
81+
82+
| Prop | Type | Description |
83+
| ---- | ---- | ----------- |
84+
| items | Action[] | Collection of actions for list |
85+
| sections | Section[] | Collection of sectioned action items |
86+
87+
## Examples
88+
89+
### Action list in a popover
90+
91+
Use for the least important actions so the merchant isn’t distracted by secondary tasks. Can also be used for a set of actions that won’t fit in the available screen space.
92+
93+
```jsx
94+
<div style={{height: '200px'}}>
95+
<Popover
96+
active
97+
activator={<Button>Actions</Button>}
98+
>
99+
<ActionList
100+
items={[
101+
{content: 'Import file'},
102+
{content: 'Export file'},
103+
]}
104+
/>
105+
</Popover>
106+
</div>
107+
```
108+
109+
### Action list with icons or image
110+
111+
Use when the items benefit from an associated action or image (e.g. a list of products).
112+
113+
```jsx
114+
<div style={{height: '200px'}}>
115+
<Popover
116+
active
117+
activator={<Button>Actions</Button>}
118+
>
119+
<ActionList
120+
items={[
121+
{content: 'Import file', icon: 'import'},
122+
{content: 'Export file', icon: 'export'},
123+
]}
124+
/>
125+
</Popover>
126+
</div>
127+
```
128+
129+
### Sectioned action list
130+
131+
Use when the items benefit from sections to help differentiate actions.
132+
133+
```jsx
134+
<div style={{height: '200px'}}>
135+
<Popover
136+
active
137+
activator={<Button>Actions</Button>}
138+
>
139+
<ActionList
140+
sections={[{
141+
title: "File options",
142+
items: [
143+
{content: 'Import file', icon: 'import'},
144+
{content: 'Export file', icon: 'export'},
145+
]
146+
}]}
147+
/>
148+
</Popover>
149+
</div>
150+
```

‎src/components/Avatar/README.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
name: Avatar
3+
tags:
4+
- thumbnail
5+
- photo
6+
- picture
7+
- profile
8+
category: Images and icons
9+
---
10+
11+
# Avatar
12+
13+
Avatars are used to show a thumbnail representation of an individual or
14+
business in the interface.
15+
16+
**Problem**
17+
18+
A merchant may manage multiple businesses on Shopify or may have more than one
19+
person working in a store.
20+
21+
**Solution**
22+
23+
Avatars visually clarify the business or the person being represented at
24+
various locations in the interface.
25+
26+
> **Not what you’re looking for?**
27+
>* To create page-level layout, [use the layout component](/components/structure/layout).
28+
29+
---
30+
31+
## Best practices
32+
33+
Avatars should be one of 3 sizes:
34+
35+
* Small (32 x 32px): use when the medium size is too big for the layout, or when the avatar has less importance
36+
* Medium (40 x 40px): use as the default size
37+
* Large (60 x 60px): use when an avatar is a focal point (e.g. on a single customer card)
38+
39+
---
40+
41+
## Content guidelines
42+
43+
Any time you use an image to communicate a concept on Shopify, it’s important to use descriptive [alt text](/content/alternative-text). Doing this is important for [accessibility](/principles/accessibility) because it allows screen readers to describe what’s in the image to people who may not be able to see it.
44+
45+
For avatars, we recommend using a format that describes what will show in the
46+
image:
47+
48+
* alt="person’s name" if the avatar represents a person
49+
* alt="business’s name" if the avatar represents a business
50+
* alt="" if the name of the person/business appears next to the avatar as text
51+
52+
| Prop | Type | Description |
53+
| ---- | ---- | ----------- |
54+
| size | enum['small', 'medium', 'large'] | Size of avatar |
55+
| name | string | The name of the person |
56+
| initials | string | Initials of person to display |
57+
| customer | boolean | Whether the avatar is for a customer |
58+
| source | string | URL of the avatar image |
59+
| accessibilityLabel | string | Accessible label for the avatar image |
60+
61+
## Examples
62+
63+
### Default avatar
64+
65+
Use to present an avatar for a merchant, customer, or business.
66+
67+
```jsx
68+
<Avatar customer name="Farrah" />
69+
```

0 commit comments

Comments
 (0)