Skip to content
GitLab

Introduce markdownlinting

Merged Kate Higa requested to merge kh-markdown-lint into main
Compare
and
16 files
+ 190
- 66
.github/‎workflows‎
ci.‎yml‎ +13 -2
deplo‎y.yml‎ +1 -1
deploy_pr‎eview.yml‎ +1 -1
con‎tent‎
compo‎nents‎
component-documen‎tation-guidelines‎
component-document‎ation-guidelines.md‎ +1 -1
data-ta‎ble.mdx‎ +1 -1
found‎ations‎
colo‎r.mdx‎ +37 -37
typogra‎phy.mdx‎ +3 -3
ui-pa‎tterns‎
button-u‎sage.mdx‎ +2 -2
empty-st‎ates.mdx‎ +1 -1
feature-onb‎oarding.mdx‎ +2 -2
form‎s.mdx‎ +2 -2
messag‎ing.mdx‎ +1 -1
do‎cs‎
conte‎nt.md‎ +1 -1
.markdownli‎nt-cli2.cjs‎ +19 -0
packag‎e.json‎ +4 -1
yarn‎.lock‎ +101 -10
.github/workflows/ci.yml
+ 13
- 2
name: Lint
on: [push]
jobs:
all:
eslint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@master
@@ -10,5 +10,16 @@ jobs:
version: 14
- name: install
run: yarn
- name: lint
- name: Lint with ESLint
run: yarn lint
markdownlint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@master
- uses: actions/setup-node@master
with:
version: 14
- name: install
run: yarn
- name: Lint with markdownlint
run: yarn markdownlint
.github/workflows/deploy.yml
+ 1
- 1
@@ -17,7 +17,7 @@ jobs:
# SHA for security hardening. Points at last verified HEAD of main branch.
uses: primer/.github/.github/workflows/deploy.yml@0cec9b9914f358846163f2428663b58da41028c9
with:
node_version: 12
node_version: 14
    • Kate Higa
      Kate Higa @khiga8 ·
      Author Contributor

      I upgraded the node_version for compatability with markdownlint-cli2 node dependency. I saw ci.yml already uses node_version: 14 so assuming this is fine but let me know otherwise!

Please register or sign in to reply
install: yarn
build: yarn build
output_dir: public
.github/workflows/deploy_preview.yml
+ 1
- 1
@@ -17,7 +17,7 @@ jobs:
secrets:
gh_token: ${{ secrets.GITHUB_TOKEN }}
with:
node_version: 12
node_version: 14
install: yarn
build: yarn build:preview
output_dir: public
content/components/component-documentation-guidelines/component-documentation-guidelines.md
+ 1
- 1
@@ -19,7 +19,7 @@ When documenting components, consider the core elements needed to convey its mai
See our full [documentation guidelines here](https://primer.style/contribute/documentation/).
#### Types of components
### Types of components
- **Regular**: Standard components used to build Primer UI. See [ActionList](https://primer.style/design/components/action-list).
- **Internal**: Components used by other components that do not exist on their own. See [Overlay](https://primer.style/react/Overlay).
- **Behavioral**: Components with no real anatomy or structure, rather behaviors. See [Truncate](https://primer.style/react/Truncate).
content/components/data-table.mdx
+ 1
- 1
@@ -164,7 +164,7 @@ These factors make it difficult to recommend an “ideal” page size for all us
#### Communicate when the table has no data to show
Show a [Blankslate]() component in place of the table
Show a `Blankslate` component in place of the table
#### Consider small screens
content/foundations/color.mdx
+ 37
- 37
@@ -32,7 +32,7 @@ For example use `bg-default` for the background of the page and `fg-default` for
src="https://user-images.githubusercontent.com/813754/187436947-875dbf46-1b26-42da-b96f-e7cbe315f0eb.png"
/>
#### Color design tokens are grouped based on their purpose:
### Color design tokens are grouped based on their purpose:
- **Presentational:** To represent a color. For example, the color steps in the Primer scale are named by color and lightness, such as `scale.blue.5`. These design tokens don't support color modes.
- **Functional:** To convey a meaning or a state. For example, from a functional perspective the color green is used to reinforce positive messaging. In a functional system, green design tokens are named with the suffix `.success`.
@@ -74,21 +74,21 @@ Foreground elements are **text and icons**. You can apply color to them by using
| Foundations | Usage |
| :-------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------- |
| ![](https://swatch-sid.vercel.app?mode=light&token=fg.default) `fg.default` | Primary color for text and icons in any given interface. It should be used for body content, titles and labels. |
| ![](https://swatch-sid.vercel.app?mode=light&token=fg.muted) `fg.muted` | Use for content that is secondary or that provides additional context but is not critical to understanding the flow of an interface. |
| ![](https://swatch-sid.vercel.app?mode=light&token=fg.subtle) `fg.subtle` | Use for placeholder text, icons or decorative foregrounds. |
| ![](https://swatch-sid.vercel.app?mode=light&token=fg.onEmphasis) `fg.onEmphasis` | On emphasis is the text color designed to combine with `.emphasis` backgrounds for optimal contrast. |
| ![""](https://swatch-sid.vercel.app?mode=light&token=fg.default) `fg.default` | Primary color for text and icons in any given interface. It should be used for body content, titles and labels. |
| ![""](https://swatch-sid.vercel.app?mode=light&token=fg.muted) `fg.muted` | Use for content that is secondary or that provides additional context but is not critical to understanding the flow of an interface. |
| ![""](https://swatch-sid.vercel.app?mode=light&token=fg.subtle) `fg.subtle` | Use for placeholder text, icons or decorative foregrounds. |
| ![""](https://swatch-sid.vercel.app?mode=light&token=fg.onEmphasis) `fg.onEmphasis` | On emphasis is the text color designed to combine with `.emphasis` backgrounds for optimal contrast. |
| Color roles | Usage |
| :------------------------------------------------------------------------------ | :------------------------------------------------------------------ |
| ![](https://swatch-sid.vercel.app?mode=light&token=accent.fg) `fg.accent` | Use for interactive text or icons like links or buttons. |
| ![](https://swatch-sid.vercel.app?mode=light&token=success.fg) `fg.success` | Use to emphasize a positive message. |
| ![](https://swatch-sid.vercel.app?mode=light&token=attention.fg) `fg.attention` | Use to highlight text or icons that require the user's attention. |
| ![](https://swatch-sid.vercel.app?mode=light&token=danger.fg) `fg.danger` | Use to emphasize an error or a blocking status. Action is required. |
| ![](https://swatch-sid.vercel.app?mode=light&token=severe.fg) `fg.severe` | Use to emphasize a level of severity between attention and danger. |
| ![](https://swatch-sid.vercel.app?mode=light&token=open.fg) `fg.open` | Use to style text that refers to open tasks or workflows. |
| ![](https://swatch-sid.vercel.app?mode=light&token=closed.fg) `fg.closed` | Use to style text that refers to closed tasks or workflows. |
| ![](https://swatch-sid.vercel.app?mode=light&token=done.fg) `fg.done` | Use to style text that refers to completed tasks or workflows. |
| ![""](https://swatch-sid.vercel.app?mode=light&token=accent.fg) `fg.accent` | Use for interactive text or icons like links or buttons. |
| ![""](https://swatch-sid.vercel.app?mode=light&token=success.fg) `fg.success` | Use to emphasize a positive message. |
| ![""](https://swatch-sid.vercel.app?mode=light&token=attention.fg) `fg.attention` | Use to highlight text or icons that require the user's attention. |
| ![""](https://swatch-sid.vercel.app?mode=light&token=danger.fg) `fg.danger` | Use to emphasize an error or a blocking status. Action is required. |
| ![""](https://swatch-sid.vercel.app?mode=light&token=severe.fg) `fg.severe` | Use to emphasize a level of severity between attention and danger. |
| ![""](https://swatch-sid.vercel.app?mode=light&token=open.fg) `fg.open` | Use to style text that refers to open tasks or workflows. |
| ![""](https://swatch-sid.vercel.app?mode=light&token=closed.fg) `fg.closed` | Use to style text that refers to closed tasks or workflows. |
| ![""](https://swatch-sid.vercel.app?mode=light&token=done.fg) `fg.done` | Use to style text that refers to completed tasks or workflows. |
### Backgrounds
@@ -96,22 +96,22 @@ Background colors apply to surfaces of components or UI elements, such as pages,
| Foundations | Usage |
| :------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------- |
| ![](https://swatch-sid.vercel.app?mode=light&token=neutral.emphasisPlus) `bg.emphasis` | Provides the highest contrast against the default background, such as in tooltips. |
| ![](https://swatch-sid.vercel.app?mode=light&token=canvas.default) `bg.default` | Primary background color. |
| ![](https://swatch-sid.vercel.app?mode=light&token=canvas.subtle) `bg.subtle` | Provides visual rest and contrast against the default background. |
| ![](https://swatch-sid.vercel.app?mode=light&token=canvas.inset) `bg.inset` | Can be used instead of the default background to create a focal point, such as in conversations or activity feeds. |
| ![""](https://swatch-sid.vercel.app?mode=light&token=neutral.emphasisPlus) `bg.emphasis` | Provides the highest contrast against the default background, such as in tooltips. |
| ![""](https://swatch-sid.vercel.app?mode=light&token=canvas.default) `bg.default` | Primary background color. |
| ![""](https://swatch-sid.vercel.app?mode=light&token=canvas.subtle) `bg.subtle` | Provides visual rest and contrast against the default background. |
| ![""](https://swatch-sid.vercel.app?mode=light&token=canvas.inset) `bg.inset` | Can be used instead of the default background to create a focal point, such as in conversations or activity feeds. |
| Color roles | Usage |
| :----------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------- |
| ![](https://swatch-sid.vercel.app?mode=light&token=accent.subtle) `bg.accent` | Use to accentuate interactive areas in the UI like selected elements. |
| ![](https://swatch-sid.vercel.app?mode=light&token=success.subtle) `bg.success` | Use to highlight a positive message. |
| ![](https://swatch-sid.vercel.app?mode=light&token=attention.subtle) `bg.attention` | Use to highlight elements that require a user's attention or pending statuses. |
| ![](https://swatch-sid.vercel.app?mode=light&token=danger.subtle) `bg.danger` | Use to emphasize an error or a blocking status, where action is required. |
| ![](https://swatch-sid.vercel.app?mode=light&token=severe.subtle) `bg.severe` | Use to emphasize an extra level of severity between attention and danger. |
| ![](https://swatch-sid.vercel.app?mode=light&token=open.subtle) `bg.open` | Use to style text that refers to open tasks or workflows. |
| ![](https://swatch-sid.vercel.app?mode=light&token=closed.subtle) `bg.closed` | Use to style text that refers to closed tasks or workflows. |
| ![](https://swatch-sid.vercel.app?mode=light&token=done.subtle) `bg.done` | Use to style text that refers to completed tasks or workflows. |
| ![](https://swatch-sid.vercel.app?mode=light&token=accent.emphasis) `bg.[ANY_OF_ABOVE].emphasis` | Use to highlight the most important item of a view or an interface. |
| ![""](https://swatch-sid.vercel.app?mode=light&token=accent.subtle) `bg.accent` | Use to accentuate interactive areas in the UI like selected elements. |
| ![""](https://swatch-sid.vercel.app?mode=light&token=success.subtle) `bg.success` | Use to highlight a positive message. |
| ![""](https://swatch-sid.vercel.app?mode=light&token=attention.subtle) `bg.attention` | Use to highlight elements that require a user's attention or pending statuses. |
| ![""](https://swatch-sid.vercel.app?mode=light&token=danger.subtle) `bg.danger` | Use to emphasize an error or a blocking status, where action is required. |
| ![""](https://swatch-sid.vercel.app?mode=light&token=severe.subtle) `bg.severe` | Use to emphasize an extra level of severity between attention and danger. |
| ![""](https://swatch-sid.vercel.app?mode=light&token=open.subtle) `bg.open` | Use to style text that refers to open tasks or workflows. |
| ![""](https://swatch-sid.vercel.app?mode=light&token=closed.subtle) `bg.closed` | Use to style text that refers to closed tasks or workflows. |
| ![""](https://swatch-sid.vercel.app?mode=light&token=done.subtle) `bg.done` | Use to style text that refers to completed tasks or workflows. |
| ![""](https://swatch-sid.vercel.app?mode=light&token=accent.emphasis) `bg.[ANY_OF_ABOVE].emphasis` | Use to highlight the most important item of a view or an interface. |
### Borders
@@ -119,20 +119,20 @@ Borders can be used to group content or to create a visible separation between s
| Foundations | Usage |
| :---------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------ |
| ![](https://swatch-sid.vercel.app?mode=light&token=border.default) `border.default` | Use to create bounds around content, for example elements inside a card. Default borders are critical to understanding a page layout. |
| ![](https://swatch-sid.vercel.app?mode=light&token=border.muted) `border.muted` | Use for dividers to emphasize the separation between items, columns or sections. |
| ![""](https://swatch-sid.vercel.app?mode=light&token=border.default) `border.default` | Use to create bounds around content, for example elements inside a card. Default borders are critical to understanding a page layout. |
| ![""](https://swatch-sid.vercel.app?mode=light&token=border.muted) `border.muted` | Use for dividers to emphasize the separation between items, columns or sections. |
| Color roles | Usage |
| :------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------- |
| ![](https://swatch-sid.vercel.app?mode=light&token=accent.muted) `border.accent` | Use to accentuate interactive areas in the UI like selected elements. |
| ![](https://swatch-sid.vercel.app?mode=light&token=success.muted) `border.success` | Use to highlight a positive message. |
| ![](https://swatch-sid.vercel.app?mode=light&token=attention.muted) `border.attention` | Use to highlight elements that require a users attention or pending statuses. |
| ![](https://swatch-sid.vercel.app?mode=light&token=danger.muted) `border.danger` | Use to emphasize an error or a blocking status. Action is required. |
| ![](https://swatch-sid.vercel.app?mode=light&token=severe.muted) `border.severe` | Use to emphasize an extra level of severity between attention and danger. |
| ![](https://swatch-sid.vercel.app?mode=light&token=open.muted) `border.open` | Use to style text that refers to open tasks or workflows. |
| ![](https://swatch-sid.vercel.app?mode=light&token=closed.muted) `border.closed` | Use to style text that refers to closed tasks or workflows. |
| ![](https://swatch-sid.vercel.app?mode=light&token=done.muted) `border.done` | Use to style text that refers to completed tasks or workflows. |
| ![](https://swatch-sid.vercel.app?mode=light&token=accent.emphasis) `border.[ROLE].emphasis` | Use to highlight the most important item of a view or an interface. |
| ![""](https://swatch-sid.vercel.app?mode=light&token=accent.muted) `border.accent` | Use to accentuate interactive areas in the UI like selected elements. |
| ![""](https://swatch-sid.vercel.app?mode=light&token=success.muted) `border.success` | Use to highlight a positive message. |
| ![""](https://swatch-sid.vercel.app?mode=light&token=attention.muted) `border.attention` | Use to highlight elements that require a users attention or pending statuses. |
| ![""](https://swatch-sid.vercel.app?mode=light&token=danger.muted) `border.danger` | Use to emphasize an error or a blocking status. Action is required. |
| ![""](https://swatch-sid.vercel.app?mode=light&token=severe.muted) `border.severe` | Use to emphasize an extra level of severity between attention and danger. |
| ![""](https://swatch-sid.vercel.app?mode=light&token=open.muted) `border.open` | Use to style text that refers to open tasks or workflows. |
| ![""](https://swatch-sid.vercel.app?mode=light&token=closed.muted) `border.closed` | Use to style text that refers to closed tasks or workflows. |
| ![""](https://swatch-sid.vercel.app?mode=light&token=done.muted) `border.done` | Use to style text that refers to completed tasks or workflows. |
| ![""](https://swatch-sid.vercel.app?mode=light&token=accent.emphasis) `border.[ROLE].emphasis` | Use to highlight the most important item of a view or an interface. |
## Functional system in action
content/foundations/typography.mdx
+ 3
- 3
@@ -29,19 +29,19 @@ We utilize system fonts at GitHub, which allow for optimized performance. This d
**System Fonts**—default GitHub font-stack with ample fallbacks alongside emoji support
```
```css
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol";
```
**Monospace**—used within GitHub product to display metadata or captions, and used in marketing contexts as subheaders
```
```css
$mono-font: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, Courier, monospace !default;
```
**Display face**—the font stack that implements Inter UI
```
```css
font-family: InterUI, -apple-system, BlinkMacSystemFont, "Helvetica Neue", "Segoe UI", Oxygen, Ubuntu, Cantarell, "Open Sans", sans-serif;
```
content/ui-patterns/button-usage.mdx
+ 2
- 2
@@ -116,13 +116,13 @@ Buttons that only use an icon should still have a label that is invisible to sig
Counters can be added in appropriate scenarios to provide context. For example, showing social proof by displaying the number of people watching a repo.
#### Counter inside button
### Counter inside button
A count can be displayed inside of a button using a [CounterLabel](https://primer.style/react/CounterLabel).
![button with count inside](https://user-images.githubusercontent.com/2313998/129626580-465111c8-9237-4e33-af42-b2e830ea9cc3.png)
#### Counter attached to a button
### Counter attached to a button
A count can be displayed as a separate element that is attached to a button. Only display a count as separate element that is attached to a button when the button uses the "small" size variant and the button type is "Default" or "Outline".
content/ui-patterns/empty-states.mdx
+ 1
- 1
@@ -29,7 +29,7 @@ Blankslates can and are encouraged to use one primary action. This button should
### Secondary action
Secondary actions are optional and are represented by a text link located below the primary action button. A secondary action is used to direct a user to additional content about the feature. This might look like "[Learn more about X](#)" or "[Check out the guide on X](#)" or simply "[Learn more](#)".
Secondary actions are optional and are represented by a text link located below the primary action button. A secondary action is used to direct a user to additional content about the feature. This might look like `Learn more about X` or "`Check out the guide on X`.
### Border
content/ui-patterns/feature-onboarding.mdx
+ 2
- 2
@@ -133,7 +133,7 @@ Treat feature onboarding as a story or a journey with a beginning, middle, and e
A teaching bubble is a [popover](https://primer.style/css/components/popover) that calls attention to a feature in a specific part of the page. Generally, teaching bubbles should be used to educate the user and enrich the task at hand.
### Usage guidelines
### Usage guidelines for teaching bubble
Teaching bubble Figma [sticker sheet](https://www.figma.com/file/Y2xJLFBrU7yyiDLlEkQXcF/Primer-Interfaces?node-id=2%3A1295&t=2xX6FwLSJ0Cq9Qkp-1).
@@ -313,7 +313,7 @@ Use inline banners in a page with multiple steps or actions.
Use empty states as an integrated way to onboard users to new features. Read more about [empty states](/ui-patterns/empty-states).
**In-product marketing empty state**
#### In-product marketing empty state
For special occasions, a first time experience may be more unique than the typical blank state. Take a more branded approach to engage and guide the user through complex experiences. Be aware of how the experience will change once the first-time UI is no longer there.
content/ui-patterns/forms.mdx
+ 2
- 2
@@ -35,7 +35,7 @@ A caption may be used to provide additional context about the field to help user
Caption text may be displayed alongside a validation message, or it may be hidden if it only provides redundant information.
Caption text may be used to augment the [label](#label), but should not be redundant with the label or any other parts of the form control. If the caption feels redundant, try removing it.
Caption text may be used to augment the [label](#label-required), but should not be redundant with the label or any other parts of the form control. If the caption feels redundant, try removing it.
<DoDontContainer>
<Do>
@@ -104,7 +104,7 @@ For more information about form validation, see the [validation guidelines](#val
![Text input, open-ended autocomplete text input, plain text input, textarea](https://user-images.githubusercontent.com/2313998/170069913-325a987b-9a75-4e83-826a-bb7ae73d6831.png)
Use an open-ended text field when the field does not have a list of possible values. If the input is able to suggest values, use [autocomplete](#autocomplete) to allow users to pick a value or enter their own.
Use an open-ended text field when the field does not have a list of possible values. If the input is able to suggest values, use [autocomplete](/components/avatar-pair) to allow users to pick a value or enter their own.
### A set of selectable options
content/ui-patterns/messaging.mdx
+ 1
- 1
@@ -60,7 +60,7 @@ Toasts should be brief and not bog down the experience with superfluous copy. If
### Accessibility
Toasts are non-modal components and should contain `role=log`, which implies the element has `aria-live="polite"`. This notifies the user of the toast via Assistance Technologies without having to change focus to the toast. You can read more about `role=log` [here](https://www.w3.org/WAI/WCAG21/Techniques/aria/ARIA23).
Toasts are non-modal components and should contain `role=log`, which implies the element has `aria-live="polite"`. This notifies the user of the toast via Assistance Technologies without having to change focus to the toast. You can read more about `role=log` at [W3: Using `role=log` to identify sequential information updates](https://www.w3.org/WAI/WCAG21/Techniques/aria/ARIA23).
Toasts are generally informative and should not receive focus when they appear. For that reason, we suggest you **avoid using interactive elements** in the component (aside from a dismiss action). Keep in mind that, even without an explicit dismiss action, the user can always hit `esc` to dismiss the toast. For more information on how interactive children affect web accessibility, [check out this issue](https://github.com/jackbsteinberg/std-toast/issues/29).