Skip to content

Commit

Permalink
Uplifted Content Design Pages (#13012)
Browse files Browse the repository at this point in the history
### WHY are these changes introduced?

Updated content design pages based on uplift work to bring our published
standards in line with current standards. These are updates to
documentation only for polaris.shopify.com.

### WHAT is this pull request doing?

- New Fundamentals page to replace the Product content page
- Remove pages no longer needed (Actionable language, Help content, Help
documentation, Merchant-to-customer content, and Voice and tone)
- Updated Grammar page
- Updated Error messages page
- Updated page order for side nav
- Moved button  content guidelines to button compontent page
- Added redirects for removed pages

<img width="1370" alt="Shopify Polaris Content Guidelines"
src="https://github.com/user-attachments/assets/e3bc526a-d56c-4376-b343-058326d2a1fc"
/>

### How to 🎩

🖥 [Local development
instructions](https://github.com/Shopify/polaris/blob/main/README.md#install-dependencies-and-build-workspaces)
🗒 [General tophatting
guidelines](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting.md)
📄 [Changelog
guidelines](https://github.com/Shopify/polaris/blob/main/.github/CONTRIBUTING.md#changelog)

### 🎩 checklist

- [ ] Tested a
[snapshot](https://github.com/Shopify/polaris/blob/main/documentation/Releasing.md#-snapshot-releases)
- [ ] Tested on
[mobile](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting.md#cross-browser-testing)
- [x] 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)
- [x] Updated the component's `README.md` with documentation changes
- [x] [Tophatted
documentation](https://github.com/Shopify/polaris/blob/main/documentation/Tophatting%20documentation.md)
changes in the style guide
  • Loading branch information
qdietrich authored Jan 7, 2025
1 parent 16421c4 commit 416f25c
Show file tree
Hide file tree
Showing 17 changed files with 517 additions and 3,545 deletions.
2 changes: 2 additions & 0 deletions .changeset/orange-spoons-fix.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
---
---
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ Button groups should:

## Content guidelines

Button groups should follow the [content guidelines](https://polaris.shopify.com/content/actionable-language#buttons) for buttons.
Button groups should follow the [content guidelines](https://polaris.shopify.com/components/actions/button#content-guidelines) for buttons.

---

Expand Down
55 changes: 54 additions & 1 deletion polaris.shopify.com/content/components/actions/button.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -117,7 +117,60 @@ The HTML that renders for the `Button` and `Link` components carries meaning. Us

## Content guidelines

Buttons should follow the content guidelines for [buttons](https://polaris.shopify.com/content/actionable-language#buttons).
{/* keywords: buttons, button copy, button text, button content, links, actions, calls to action, call to actions, action-led, action led, scannable, articles, choose , select, choose vs select, select vs choose, need, must, need vs must, must vs need --> --> */}

Buttons need to be clear and predictable. Merchants should be able to anticipate what will happen when they select a button. Never mislead someone by mislabeling a button.

- Use universally understood iconography instead of words wherever you can
- Buttons can include an icon or text, or both
- Verbs like “View” or “Go” or “Read” are often unnecessary since the button itself already conveys these actions
- Sentence case
- No articles (“a” “an” “the”)
- No punctuation

<DoDont>

#### Do

- Save
- Edit
- Add tags

#### Don’t

- Save product
- Edit collection
- Add tag(s)

</DoDont>

Always write button text in sentence case, which means the first word is capitalized and the rest are lowercase (unless a term is a proper noun).

<DoDont>

#### Do

- Buy new domain

#### Don’t

- Buy New Domain

</DoDont>

Avoid unnecessary words and articles such as “the,” “an,” or “a.”

<DoDont>

#### Do

Add menu item

#### Don’t

Add a menu item

</DoDont>

---

Expand Down
Loading

0 comments on commit 416f25c

Please sign in to comment.