diff --git a/.github/contributing.md b/.github/contributing.md index a59930fa3..66f3647f5 100644 --- a/.github/contributing.md +++ b/.github/contributing.md @@ -1,7 +1,7 @@ # Contributing ## Creating pages -To create a new page, just create a new file in the `pages/design` directory. (Note: pages outside of the `design` subdirectory will not be accessible from `primer.style/design`!) +To create a new page, just create a new file in the `pages/design` directory. (Note: pages outside of the `design` subdirectory will not be accessible from `primer.style`!) The URL for each page reflects its path within the `pages` directory, so: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 97e3da6b5..c9b8c8ddf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,7 +9,7 @@ If you are writing documentation, please read the [documentation guidelines](htt ## Design guidelines template Even though some guidelines follow a different format, most can use the following template as a starting point. Required sections are indicated. -đź’ˇ The [action list component](https://primer.style/design/components/action-list) documentation is a good example of design guidelines. +đź’ˇ The [action list component](https://primer.style/components/action-list) documentation is a good example of design guidelines. | Section | Description | Notes | |--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------| diff --git a/README.md b/README.md index ca35aad75..7797d8c65 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,10 @@ -# Primer Design System documentation +# Primer Design System documentation -Documentation for all things Primer, including components, UI patterns, foundations, guides, and more. +Documentation for all things Primer, including components, UI patterns, foundations, guides, and more. ## Status -This repository is evolving as our documentation needs change. See our [contribution guides here](https://primer.style/design/guides/contribute/documentation). +This repository is evolving as our documentation needs change. See our [contribution guides here](https://primer.style/guides/contribute/documentation). [Project board](https://github.com/orgs/github/projects/4503/views/16) (GitHub staff only) @@ -24,16 +24,16 @@ This repository is evolving as our documentation needs change. See our [contribu ## Deployment -We deploy this site using [GitHub Pages](https://pages.github.com/). Every push to a branch other than `main` will deploy to a URL unique to the preview environment. Merges to `main` will automatically deploy the site to `https://primer.style/design/`. +We deploy this site using [GitHub Pages](https://pages.github.com/). Every push to a branch other than `main` will deploy to a URL unique to the preview environment. Merges to `main` will automatically deploy the site to `https://primer.style/`. ## FAQ -### How do I add documentation for a new component or edit existing component documentation? -- Our [component documentation files are found here](https://github.com/primer/design/tree/main/content/components), and guidelines for adding content can be found under the [Documenting components](https://primer.style/design/guides/contribute/documentation#documenting-components) section of the [Contributing guidelines]((https://primer.style/design/guides/contribute/documentation)). -- For a more detailed walk-through, check out this [tutorial video](https://www.loom.com/share/ac56f610076f41878d0351b4a1c44a6b?sid=1bd5a46d-a7ea-4e0d-bb08-ed9e8c8bfe12). +### How do I add documentation for a new component or edit existing component documentation? +- Our [component documentation files are found here](https://github.com/primer/design/tree/main/content/components), and guidelines for adding content can be found under the [Documenting components](https://primer.style/guides/contribute/documentation#documenting-components) section of the [Contributing guidelines]((https://primer.style/guides/contribute/documentation)). +- For a more detailed walk-through, check out this [tutorial video](https://www.loom.com/share/ac56f610076f41878d0351b4a1c44a6b?sid=1bd5a46d-a7ea-4e0d-bb08-ed9e8c8bfe12). -### I need help getting started. -- Check out our [getting started guides](https://primer.style/design/guides) or ping us in [Slack](https://github.slack.com/archives/CSGAVNZ19) (GitHub staff only) +### I need help getting started. +- Check out our [getting started guides](https://primer.style/guides) or ping us in [Slack](https://github.slack.com/archives/CSGAVNZ19) (GitHub staff only) ### I noticed a bug in the documentation! - Feel free to open a pull request or issue directly in this repository, or ping us in [Slack](https://github.slack.com/archives/CSGAVNZ19) (GitHub staff only) diff --git a/content/components/action-menu.mdx b/content/components/action-menu.mdx index 3fcb83e43..63fc9f46e 100644 --- a/content/components/action-menu.mdx +++ b/content/components/action-menu.mdx @@ -419,8 +419,8 @@ On smaller viewports, the menu should always be re-positioned to fit within the Here is an overview of [action list](/components/action-menu) items that are compatible with menus: - **Action**: Triggers an action or dialog. Trailing visuals can be used for keyboard shortcuts. -- **Single/multi select**: Represented by a [check](/design/foundations/icons/check-16) and never a HTML checkbox. Trailing visuals can be used for keyboard shortcuts. -- **Submenu**: Represented by a [chevron-right](/design/foundations/icons/chevron-right-16) as a trailing visual. +- **Single/multi select**: Represented by a [check](/foundations/icons/check-16) and never a HTML checkbox. Trailing visuals can be used for keyboard shortcuts. +- **Submenu**: Represented by a [chevron-right](/foundations/icons/chevron-right-16) as a trailing visual. - **Section header**: To add clarification to a section. - **Divider**: To create sections for your selections, actions or submenus. diff --git a/content/components/button-group.mdx b/content/components/button-group.mdx index 4775a3979..713b2eb16 100644 --- a/content/components/button-group.mdx +++ b/content/components/button-group.mdx @@ -39,7 +39,7 @@ Grouping buttons with a button group is better than rendering buttons close toge - Avoid grouping too many buttons together. It could be overwhelming to the user. - Do not use a button group to indicate a selection. Use a [segmented control](/components/segmented-control) instead. - Do not use a button group as a replacement for tab navigation. -- Avoid mixing buttons with text labels with icon-only buttons. However, it is acceptable to group a text-labeled button with an icon-only button with a [down-pointing triangle](https://primer.style/design/foundations/icons/triangle-down-16) that opens a dropdown menu of actions related to the button. +- Avoid mixing buttons with text labels with icon-only buttons. However, it is acceptable to group a text-labeled button with an icon-only button with a [down-pointing triangle](https://primer.style/foundations/icons/triangle-down-16) that opens a dropdown menu of actions related to the button. - Do not group an [invisible](/components/button#invisible) button with buttons of another variant. ## Options diff --git a/content/components/selectpanel.mdx b/content/components/selectpanel.mdx index df9b0822a..ae748589a 100644 --- a/content/components/selectpanel.mdx +++ b/content/components/selectpanel.mdx @@ -485,7 +485,7 @@ When adding an extra action in the footer, it is important to ensure that it sti src="https://github.com/primer/design/assets/980622/ae6d19c2-7bfa-4357-be65-341c0728b9a8" /> -See the [Dialog guidelines](https://primer.style/design/components/dialog) for more details. +See the [Dialog guidelines](https://primer.style/components/dialog) for more details. ## Keyboard navigation diff --git a/content/components/toggle-switch.mdx b/content/components/toggle-switch.mdx index 6a58b990c..97cf63faa 100644 --- a/content/components/toggle-switch.mdx +++ b/content/components/toggle-switch.mdx @@ -148,7 +148,7 @@ import {AccessibilityLink} from '~/src/components/accessibility-link' sx={{gap: 3}} > - The progressive disclosure pattern may be used to hide or + The progressive disclosure pattern may be used to hide or show content based on whether a toggle switch is on. Content revealed on toggle switch activation should always come{' '} after the toggle switch. diff --git a/content/components/token.mdx b/content/components/token.mdx index e8257f8c5..13efe7537 100644 --- a/content/components/token.mdx +++ b/content/components/token.mdx @@ -188,7 +188,7 @@ Examples of interactions: Tokens can be added or removed from a group in the way that makes the most sense for your use case. We recommend - using an autocomplete component to allow users to sort through a + using an autocomplete component to allow users to sort through a list to pick options. diff --git a/content/components/tree-view.mdx b/content/components/tree-view.mdx index 94e4feec7..522ceb198 100644 --- a/content/components/tree-view.mdx +++ b/content/components/tree-view.mdx @@ -387,7 +387,7 @@ A tree view can be a frustrating pattern if it forces users to spend a lot of ti

Inform users why the data cannot be retrieved and give them a path to resolve it. The error message cannot appear in the tree view because it is not semantically a node in the tree. Instead, the error message should appear in a{' '} - dialog with an optional call-to-action that can resolve the error. + dialog with an optional call-to-action that can resolve the error.

If the user dismisses the dialog, focus should be moved back to the collapsed parent node. If the user clicks a diff --git a/content/foundations/color.mdx b/content/foundations/color.mdx index d7879cc1b..826f931a9 100644 --- a/content/foundations/color.mdx +++ b/content/foundations/color.mdx @@ -312,7 +312,7 @@ If you work with the [functional colors](#color-roles-recipes), this work has al ### Additional guidance -Reference [Color considerations](https://primer.style/design/guides/accessibility/color-considerations) for additional information about how color relates to compliance, and other focused documentation topics. +Reference [Color considerations](https://primer.style/guides/accessibility/color-considerations) for additional information about how color relates to compliance, and other focused documentation topics. ## Color outside the functional system diff --git a/content/guides/accessibility/color-considerations.mdx b/content/guides/accessibility/color-considerations.mdx index cbc1801ec..423b2b373 100644 --- a/content/guides/accessibility/color-considerations.mdx +++ b/content/guides/accessibility/color-considerations.mdx @@ -1,6 +1,6 @@ --- title: Color considerations -description: Color is an important aspect of creating accessible, inclusive experiences. +description: Color is an important aspect of creating accessible, inclusive experiences. --- import ButtonTextOnly from '../../../src/images/accessibility/color-considerations/button-text-only.png' @@ -16,11 +16,11 @@ import ThemePicker from '../../../src/images/accessibility/color-considerations/ ## Overview -This guidance covers considerations that can't automatically be integrated into Primer. It supplements [accessibility guidance given in the Color portion of our Foundations documentation](https://primer.style/design/foundations/color#accessibility). +This guidance covers considerations that can't automatically be integrated into Primer. It supplements [accessibility guidance given in the Color portion of our Foundations documentation](https://primer.style/foundations/color#accessibility). ### Design tokens -The majority of color contrast considerations should be handled by [Primer color design tokens](https://primer.style/design/foundations/color#how-to-use-color-for-product-ui). Ensure that solutions for the following considerations integrate design tokens as a method of creating accessible experiences. +The majority of color contrast considerations should be handled by [Primer color design tokens](https://primer.style/foundations/color#how-to-use-color-for-product-ui). Ensure that solutions for the following considerations integrate design tokens as a method of creating accessible experiences. ### Determining contrast @@ -32,7 +32,7 @@ GitHub is **required** to honor WCAG AA-level compliance. This means that WCAG S An example level A Success Criterion is [SC 1.4.1 Use of Color](https://www.w3.org/WAI/WCAG21/Understanding/use-of-color.html). An example level AA Success Criterion is [SC 1.4.3 Contrast (Minimum)](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html). -## Compliance +## Compliance The following guidance is based on one or more **normative** Web Content Accessibility Guidelines (WCAG) success criterion. This means that the guidance is based on objective requirements with implications that affect [MAS-C compliance efforts](https://github.com/github/accessibility/blob/main/docs/measuring-ourselves/microsoft-accessibility-standards.md#microsoft-accessibility-standards-mas), as well as international laws regarding accessibility. @@ -40,7 +40,7 @@ An example of **the difference between non-normative and normative consideration ### Non-normative choices -A design could use a dark shade of purple as the background color as a **non-normative aesthetic choice**. Reasons for going with dark purple could be: +A design could use a dark shade of purple as the background color as a **non-normative aesthetic choice**. Reasons for going with dark purple could be: - The team prefers how it looks over dark blue, dark green, dark gray, etc., - The dark purple is a subtle reference to a brighter purple that is a core part of main palette, @@ -53,16 +53,16 @@ The **normative requirement** for going with dark purple would be [comparing the ### The APCA -The [Advanced Accessible Perceptual Contrast Algorithm](https://www.myndex.com/APCA/) (APCA) is a proposal and is **not normative**. In terms of WCAG, and therefore, MAS-C compliance, this means that color contrast is valid **only** if it meets WCAG 2.1 criteria. +The [Advanced Accessible Perceptual Contrast Algorithm](https://www.myndex.com/APCA/) (APCA) is a proposal and is **not normative**. In terms of WCAG, and therefore, MAS-C compliance, this means that color contrast is valid **only** if it meets WCAG 2.1 criteria. A color value that is APCA-compliant **might not** be WCAG-compliant until APCA is integrated into WCAG 3.0. WCAG 3.0 is still a work in progress and currently does not have an anticipated release date. ## Visual themes -GitHub offers two parent themes: +GitHub offers two parent themes: -1. Day (light), and -2. Night (dark). +1. Day (light), and +2. Night (dark). Each parent theme has a default appearance, and then a suite of sub-themes. Sub-themes include considerations for high and low contrast experiences, as well as certain vision conditions. @@ -72,11 +72,11 @@ It is possible to set GitHub to use a dark sub-theme when a parent Day theme has ### Default theme -GitHub uses: +GitHub uses: - **The default Day (light) theme** when a user visits the site in a logged out state and their operating system is set to light mode. - **The default Night (dark) theme** when a user visits the site in a logged out state and their operating system is set to dark mode. -- Whatever theme the user has set in their account settings. +- Whatever theme the user has set in their account settings. When not logged in, users are unable to adjust the theme in the [Appearance settings](https://github.com/settings/appearance). @@ -85,7 +85,7 @@ Because of this, [the default Day **and** Night theme **must both** satisfy WCAG - Pass color contrast requirements, and - Have the mechanism for accessing and changing the theme be fully WCAG compliant. -This is the strongest guarantee we have that: +This is the strongest guarantee we have that: 1. Content can be perceived—and therefore understood and used—across a wide range of vision conditions, and that 2. The mechanism to adjust GitHub's theme can be operated by the widest range of input modes. @@ -98,11 +98,11 @@ This allows users to use GitHub in a logged-out state. If a user is logged in, i Certain themes are specifically designed to create a low contrast effect, notably the Dark Dimmed sub-theme. In this use case, a user selecting this theme is likely **intentionally** expressing a desire for an experience with less visual contrast. -Like other theme selections, this may be to satisfy: +Like other theme selections, this may be to satisfy: -1. Aesthetic sensibilities, +1. Aesthetic sensibilities, 2. Access needs that are derived from visual conditions that make a higher contrast experience unusable, or -3. A combination of both. +3. A combination of both. In the case of access needs, a higher contrast experience may actually be less accessible for the user. @@ -112,10 +112,10 @@ GitHub should strive to ensure all themes that don't specifically deal with an i ### High contrast themes, high contrast mode, and forced colors mode -GitHub offers two high contrast sub-themes: +GitHub offers two high contrast sub-themes: -1. Light High Contrast, and -2. Dark High Contrast. +1. Light High Contrast, and +2. Dark High Contrast. In addition some, but **not all** operating systems offer forced color and high contrast mode experiences. @@ -129,7 +129,7 @@ High contrast themes can be enabled with or without forced color and high contra This **is not** provided by GitHub. -A high contrast mode is a signal to the operating system to increase the visual distinction between different UI elements. On the web, it is a flag that can be targeted with a media query. +A high contrast mode is a signal to the operating system to increase the visual distinction between different UI elements. On the web, it is a flag that can be targeted with a media query. The presence of an enabled high contrast mode experience does not guarantee a high contrast web experience is generated—that is an experience the website has to intentionally provide. @@ -156,7 +156,7 @@ At a high-level: - Buttons **perform a predetermined action** when pressed. Examples of this are submitting form input, triggering a dialog, or saving user-entered content. - Inputs **collect information for eventual submission**. Examples of this are single and multiline text-entry areas, checkbox selections/radio choices, and comboboxes. -Inputs and buttons are combined to form data collection and transmission experiences such as a contact form or a Pull Request submission. +Inputs and buttons are combined to form data collection and transmission experiences such as a contact form or a Pull Request submission. ### Inputs @@ -167,14 +167,14 @@ Being able to perceive the boundaries of an input is vital. Meeting WCAG color c Broadly-speaking, there are four overall considerations for input contrast: 1. Text, -2. Borders, +2. Borders, 3. Selected state, and 4. Validation state. Combined, meeting contrast requirements allow a user to understand: 1. What the input is for, -2. What area of the input a user can interact with, +2. What area of the input a user can interact with, 3. What information a user has entered into the input, and 4. What state the input is in. @@ -218,8 +218,8 @@ Validation state **must not** rely on color as the sole way of determining if an A wireframe illustration of a text input with an error message and icon. Its label reads, 'Email address.' It's user-provided text content reads, 'asdf.' The error message reads, 'Error message', and the the error icon is a warning symbol. A label pointing to the error message reads, 'Communicates validation status.' A label pointing to the text input's border reads, 'Reinforces validation status.' -- If the validation message is **only text**, it **must** meet a contrast ratio of `4.5:1` for "normal text", or `3:1` for "large text". -- If the validation message is **only** an icon, it **must** meet a contrast ratio of `3:1`. +- If the validation message is **only text**, it **must** meet a contrast ratio of `4.5:1` for "normal text", or `3:1` for "large text". +- If the validation message is **only** an icon, it **must** meet a contrast ratio of `3:1`. - If the validation message is both **text and an icon**, it **must** meet a contrast ratio of `4.5:1` for "normal text", or `3:1` for "large text". In this context the icon is considered decorative. It is still encouraged to make the icon meet a `3:1` contrast ratio, however. Contrast for validation state is calculated by the text or icon's computed color value compared to the computed background color the input is placed on. @@ -244,7 +244,7 @@ Combined, meeting contrast requirements allow a user to understand: #### Button text contrast -The visible text portion that communicates the button's purpose **must** meet a contrast ratio of `4.5:1` for "normal text", or `3:1` for "large text". +The visible text portion that communicates the button's purpose **must** meet a contrast ratio of `4.5:1` for "normal text", or `3:1` for "large text". A wireframe illustration of a button. Its text action reads, 'Cancel.' A label pointing to the text action reads, 'Communicates purpose.' A label pointing to the button's background and border reads, 'Reinforces interactive area.' @@ -259,7 +259,7 @@ Icons can either be: ##### Functional icons -If the icon is the sole means of determining a button's purpose, it is considered functional. An example of this is an [IconButton](https://primer.style/design/components/icon-button). +If the icon is the sole means of determining a button's purpose, it is considered functional. An example of this is an [IconButton](https://primer.style/components/icon-button). A wireframe illustration of a button. It only has the GitHub Octocat logo in its center, and no text. A label pointing to the icon reads, 'Communicates purpose.' A label pointing to the button's background and border reads, 'Reinforces interactive area.' @@ -271,9 +271,9 @@ Beyond the scope of normative WCAG guidance, a further consideration is if the i Buttons with a text label that **also** have an accompanying icons can consider their icons as decorative. Decorative icons **do not** need to meet WCAG-compliant contrast ratios. -The reason for this is that the text label communicates the input's purpose, provided its computed color value is WCAG compliant. The icon in this circumstance reinforces the text label. +The reason for this is that the text label communicates the input's purpose, provided its computed color value is WCAG compliant. The icon in this circumstance reinforces the text label. -An example of this is a button with both a [trash Octicon](https://primer.style/design/foundations/icons/trash-16) **and** a text label of "Delete". +An example of this is a button with both a [trash Octicon](https://primer.style/foundations/icons/trash-16) **and** a text label of "Delete". A wireframe illustration of a button. It only has the GitHub Octocat logo in its center, and no text. A label pointing to the icon reads, 'Communicates purpose.' A label pointing to the button's background and border reads, 'Reinforces interactive area.' @@ -289,7 +289,7 @@ Broadly-speaking, buttons **should not** be disabled until form validation crite If a button needs to be placed in a disabled state, [it **does not** need to be color contrast compliant](https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast.html#inactive-controls). Other WCAG criteria may affect this treatment, however. -Beyond the scope of normative WCAG guidance, a further consideration is there are other ways to visually communicate a disabled button, or to design the system in such a way that a button cannot circumstantially be placed in a disabled state. +Beyond the scope of normative WCAG guidance, a further consideration is there are other ways to visually communicate a disabled button, or to design the system in such a way that a button cannot circumstantially be placed in a disabled state. While a button's disabled state is exempt from normative compliance, consider that the control may be invisible or unpredictably disappear from the perspective of a user experiencing low vision conditions. @@ -321,7 +321,7 @@ Resources, articles, and guidelines that informed this documentation: ### Primer -- [Foundations/Color](https://primer.style/design/foundations/color) +- [Foundations/Color](https://primer.style/foundations/color) ### WCAG diff --git a/content/guides/contribute/adding-new-components.mdx b/content/guides/contribute/adding-new-components.mdx index e31b50511..f0b4ee341 100644 --- a/content/guides/contribute/adding-new-components.mdx +++ b/content/guides/contribute/adding-new-components.mdx @@ -23,7 +23,7 @@ For guidance on what makes a pattern worth sharing, check out the documentation: ### 2. Meets basic design quality checks -Check the design against the criteria in the [pattern design checklist](https://primer.style/design/guides/contribute/design#design-checklist). +Check the design against the criteria in the [pattern design checklist](https://primer.style/guides/contribute/design#design-checklist). The criteria in the pattern design checklist ensure your pattern is sturdy enough to be used in production and easily picked up by other designers or engineers. For a more detailed quality check, you can refer to the [product design checklist](https://github.com/github/product-design/blob/main/resources/design-checklist.md) (GitHub staff only). @@ -32,14 +32,14 @@ The criteria in the pattern design checklist ensure your pattern is sturdy enoug The most basic documentation your component should have: - Storybook stories demonstrate all of the pattern's features and options -- At least meets the [MVP component documentation criteria](https://github.com/primer/design/blob/main/content/components/component-documentation-guidelines/component-MVP-documentation-guidelines.md) +- At least meets the [MVP component documentation criteria](https://github.com/primer/blob/main/content/components/component-documentation-guidelines/component-MVP-documentation-guidelines.md) Documentation makes your pattern easier for others to use, and helps the team understand how your pattern could be adopted into Primer. Resources for writing documentation: -- [Component documentation criteria](https://github.com/primer/design/blob/main/content/components/component-documentation-guidelines/component-documentation-guidelines.md) -- [Primer documentation guidelines](https://primer.style/design/guides/contribute/documentation) +- [Component documentation criteria](https://github.com/primer/blob/main/content/components/component-documentation-guidelines/component-documentation-guidelines.md) +- [Primer documentation guidelines](https://primer.style/guides/contribute/documentation) ### 4. Is accessible @@ -55,7 +55,7 @@ Now your component has satisfied enough criteria that it's well on it's way to b New components should never have the same name as an existing Primer component - especially if it's distinctly different from the existing component. The only exception is if you're introducing the React implementation of a component that has already been created in [Primer ViewComponents](https://github.com/primer/view_components/). -If you're creating a modified version of an existing component, try to modify it in Primer first. If your changes are rejected by Primer, you can iterate on a "fork" of the component with a new name until it can be upstreamed. See [the flowchart](https://primer.style/design/guides/contribute/handling-new-patterns#process-summarized-as-flowchart) in the "Handling new patterns" guidelines. +If you're creating a modified version of an existing component, try to modify it in Primer first. If your changes are rejected by Primer, you can iterate on a "fork" of the component with a new name until it can be upstreamed. See [the flowchart](https://primer.style/guides/contribute/handling-new-patterns#process-summarized-as-flowchart) in the "Handling new patterns" guidelines. ## Upstreaming to Primer @@ -91,4 +91,4 @@ Primer maintainers often lack the bandwidth to do the work for you, but will do ## Adding more general patterns -If you're pitching design patterns that are lower-level than a component (for example, [data saving patterns](https://primer.style/design/ui-patterns/saving), [focus management utility](https://github.com/primer/behaviors/blob/main/docs/focus-zone.md)), you can create an issue or pull request, share your idea at the Primer patterns weekly working session (only available to GitHub staff), or post to one of Primer's Slack channels (only available to GitHub staff). +If you're pitching design patterns that are lower-level than a component (for example, [data saving patterns](https://primer.style/ui-patterns/saving), [focus management utility](https://github.com/primer/behaviors/blob/main/docs/focus-zone.md)), you can create an issue or pull request, share your idea at the Primer patterns weekly working session (only available to GitHub staff), or post to one of Primer's Slack channels (only available to GitHub staff). diff --git a/content/guides/contribute/design.mdx b/content/guides/contribute/design.mdx index 407b38d15..ef5721f99 100644 --- a/content/guides/contribute/design.mdx +++ b/content/guides/contribute/design.mdx @@ -9,7 +9,7 @@ Design flexible, robust, and repeatable patterns that build on a set of solid fo Primer is the stable trusted layer. At its foundations are typography, color, spacing, and layout. -➡️ [Primer design guidelines](https://primer.style/design/) +➡️ [Primer design guidelines](https://primer.style/) ## Upcoming patterns and proposals @@ -44,8 +44,8 @@ All design patterns for Primer Library consideration should at minimum: - [ ] **Leverage Primer**: Leverages the foundational building blocks and tools of Primer. Reuses or extends existing patterns and primitives rather than creating overrides - [ ] Colors, spacing, sizes, and typographic styles from [@primer/primitives](https://github.com/primer/primitives/) - [ ] All icons come from [@primer/octicons](https://github.com/primer/octicons/) - - [ ] Considers the criteria in the [responsive design guidelines](https://primer.style/design/foundations/responsive) + - [ ] Considers the criteria in the [responsive design guidelines](https://primer.style/foundations/responsive) - [ ] **Maintain high design quality:** Visually in harmony with GitHub UI and all visual elements are used are in their correct context - [ ] **Prioritize code as a top concern:** Designed with code quality and component API top of mind -- [ ] **Be inclusive:** Designs follow Primer [accessibility guidelines](https://primer.style/design/guides/accessibility/guidelines) and considers a global audience -- [ ] **Have documentation:** Design patterns are [documented](https://primer.style/design/guides/contribute/documentation) for easy adoption +- [ ] **Be inclusive:** Designs follow Primer [accessibility guidelines](https://primer.style/guides/accessibility/guidelines) and considers a global audience +- [ ] **Have documentation:** Design patterns are [documented](https://primer.style/guides/contribute/documentation) for easy adoption diff --git a/content/guides/development/rails/migration-guides/primer-css-tooltipped.mdx b/content/guides/development/rails/migration-guides/primer-css-tooltipped.mdx index aaf965ecc..8d08a0f7b 100644 --- a/content/guides/development/rails/migration-guides/primer-css-tooltipped.mdx +++ b/content/guides/development/rails/migration-guides/primer-css-tooltipped.mdx @@ -12,11 +12,11 @@ Depending on your usecase, there are two potential migration paths. Tooltips are not visible by default and can easily go unnoticed, so they should only be used as a last resort, and should never be used to convey critical information. -If `.tooltipped` is being set on a non-interactive element (e.g. ``, `

`, `

`), please consider an alternative. There is no way to make a tooltip fully accessible on a non-interactive element. See [Tooltip alternatives](https://primer.style/design/components/tooltip#alternatives-to-tooltips) or consult a designer. +If `.tooltipped` is being set on a non-interactive element (e.g. ``, `

`, `

`), please consider an alternative. There is no way to make a tooltip fully accessible on a non-interactive element. See [Tooltip alternatives](https://primer.style/components/tooltip#alternatives-to-tooltips) or consult a designer. ## Option 2: Migrate to the more accessible PVC tooltip -If your tooltip is appropriately set on an interactive element, you can migrate to the latest [Tooltip component](https://primer.style/design/components/tooltip/rails/alpha) which has been implemented with accessibility considerations. +If your tooltip is appropriately set on an interactive element, you can migrate to the latest [Tooltip component](https://primer.style/components/tooltip/rails/alpha) which has been implemented with accessibility considerations. ## Example scenarios @@ -61,14 +61,14 @@ Flagged code: In this above example, the information conveyed in this tooltip isn't necessarily critical but supplements the link. If we decide to permanently persist it,we can update the markup like so: ```html - Primer + Primer

``` A tooltip is also a viable option in this scenario. We can render an accessible tooltip by using the slot of the Link component and setting the tooltip type to `:description`: ```erb -<%= render(Primer::Beta::Link.new(href: "https://primer.style/design/", id: "primer-link")) do |component| %> +<%= render(Primer::Beta::Link.new(href: "https://primer.style/", id: "primer-link")) do |component| %> <% component.with_tooltip( type: :description, text: "A set of guidelines, principles, and patterns for designing and building UI at GitHub." diff --git a/content/ui-patterns/empty-states.mdx b/content/ui-patterns/empty-states.mdx index 2efd53b96..ee765ab03 100644 --- a/content/ui-patterns/empty-states.mdx +++ b/content/ui-patterns/empty-states.mdx @@ -15,7 +15,7 @@ The Blankslate is made up of several elements that work together to inform the u The graphic can bring delight, preview an interface element, or represent the goal of the feature. Graphics should be placed intentionally and with thought about the intention of the content. Graphics also differ in meaning and appeal to the user, which is why the Blankslate component has multiple variations. These variations are outlined later on this page. -If a Blankslate is being used to convey an error state, the graphic should not attempt to bring delight or be playful. Instead, the graphic should reinforce that something went wrong. Default to using the [alert icon](https://primer.style/design/foundations/icons/alert-16). +If a Blankslate is being used to convey an error state, the graphic should not attempt to bring delight or be playful. Instead, the graphic should reinforce that something went wrong. Default to using the [alert icon](https://primer.style/foundations/icons/alert-16). ### Primary Text diff --git a/content/ui-patterns/forms/overview.mdx b/content/ui-patterns/forms/overview.mdx index 506447b7c..b4fe2877f 100644 --- a/content/ui-patterns/forms/overview.mdx +++ b/content/ui-patterns/forms/overview.mdx @@ -349,7 +349,7 @@ After a form has been submitted and failed validation, you may switch to inline />
- In a flash alert at the top of the form, list the invalid + In a flash alert at the top of the form, list the invalid inputs as anchor links. When the link is activated, place focus in it's corresponding input. diff --git a/gatsby-config.js b/gatsby-config.js index 7854dff3d..9cecd24c7 100644 --- a/gatsby-config.js +++ b/gatsby-config.js @@ -10,7 +10,6 @@ module.exports = { shortName: '', description: 'Principles, standards, and usage guidelines for designing GitHub interfaces.', }, - pathPrefix: '/design', plugins: [ { resolve: '@primer/gatsby-theme-doctocat', diff --git a/package.json b/package.json index d8cf1db00..f9d426677 100644 --- a/package.json +++ b/package.json @@ -5,8 +5,8 @@ "scripts": { "start": "gatsby develop", "clean": "gatsby clean", - "build": "gatsby build --prefix-paths", - "serve": "gatsby serve --prefix-paths", + "build": "gatsby build", + "serve": "gatsby serve", "build:preview": "gatsby build", "now-build": "yarn build", "lint": "eslint .", diff --git a/src/data/team.js b/src/data/team.js index d3d527f1a..557a11b3b 100644 --- a/src/data/team.js +++ b/src/data/team.js @@ -5,8 +5,8 @@ const teamContent = [ handle: 'jesskuo4', cssFeature: `animation: jump 1s infinite`, questionOne: `Studying engineering and design, I enjoy collaborating with designers and engineers from various teams to ensure that the design system remains adaptive in addressing evolving needs. Working on design systems provides a unique opportunity to shape the foundational elements that drive consistency, branding, and cohesive user experiences across an entire organization. In addition, it allows me to learn how to look at our products and experiences at a systems-first, future-proof level.`, - questionTwo: `I'm immensely grateful for the online design community, a nurturing space where designers from all walks of life share their knowledge with the next generation— [Steve Jobs](https://www.apple.com/stevejobs/), [Julie Zhuo](https://www.juliezhuo.com/), [Ethan Eismann](https://twitter.com/eeismann) and many others. This collective effort continuously inspires my own creative journey to create accessible, beautiful, and seamless experiences. - + questionTwo: `I'm immensely grateful for the online design community, a nurturing space where designers from all walks of life share their knowledge with the next generation— [Steve Jobs](https://www.apple.com/stevejobs/), [Julie Zhuo](https://www.juliezhuo.com/), [Ethan Eismann](https://twitter.com/eeismann) and many others. This collective effort continuously inspires my own creative journey to create accessible, beautiful, and seamless experiences. + I want to express my sincerest gratitude to the design team at GitHub, who mentored and supported me in discoverying my passion for design systems: [Natalya Shelburne](http://www.artist-developer.com/), [Katie Langerman](https://www.langermank.com/), and [Cole Bemis](https://colebemis.com/). Ultimately, it is the collective wisdom, creativity, and collaborations that fuel my joy in designing.`, favoriteTools: `Copilot, Figma, Rewatch, GitHub, Youtube, Twitter, Primer.style`, avatar: 'https://avatars.githubusercontent.com/u/131988618?v=4', @@ -30,7 +30,7 @@ const teamContent = [ title: 'Engineering Manager', handle: 'raytalks', questionOne: `Having worked in and with several different software development teams before, I've learned it takes more than a process to deliver fast, reliable, high performant, quality products. - + Combining design and engineering on a stable system, while creating the most astonishing, accessible experience for our end users and developers is pure joy.`, questionTwo: `I was fortunate to have had great mentors and colleagues who supported me througout my career and taught me the nitty gritty of programming. I'm a big fan of Katrina Owen, co-founder and director of [Exercism](https://exercism.org/). I adore the work of management leaders like [Camille Fournier](https://twitter.com/skamille), and I devour books where I can learn about people like [Erin Meyer's](https://erinmeyer.com/books/the-culture-map/) The Culture Map.`, @@ -60,11 +60,11 @@ const teamContent = [ questionOne: 'I love how they foster an environment and culture of continuously learning, growing, and connecting within a community. Being able to support people in their day-to-day work is so rewarding to me, especially when these tools or resources help to improve the access of everything we make.', questionTwo: `I've always loved watching talks by [Alan Kay](https://en.wikipedia.org/wiki/Alan_Kay). The way he thinks about the future and inventing for it makes me so hopeful and excited. - + I also enjoy revisiting talks from [Sebastian Markbåge](https://twitter.com/sebmarkbage), [Nicholas Matsakis](https://twitter.com/nikomatsakis), and [Sandi Metz](https://twitter.com/sandimetz). I learn something new each time as I hear them talk about their approach to writing code and incrementally evolving complex systems over time. - + When it comes to accessibility, I am forever grateful for all the resources, writing, and presentations from [Adrian Roselli](https://twitter.com/aardrian), [Sarah Higley](https://twitter.com/codingchaos), and [Scott O'Hara](https://twitter.com/scottohara). Their work has been so influential to my own. - + Finally, when it comes to building and supporting teams I've loved going through resources from [Julie Zhou](https://twitter.com/joulee), [Lara Hogan](https://twitter.com/lara_hogan), and [Will Larson](https://twitter.com/lethain). `, favoriteTools: 'NeoVim, GitHub, ARIA APG, coffee, Figma, Spotify', @@ -157,10 +157,10 @@ const teamContent = [ title: 'Engineering Manager', handle: 'lesliecdubs', questionOne: `As an agency developer early in my career, it seemed we were always building the same UI with different styles. So why not build once, with enough flexibility to customize for many clients? - + Later, it became clear to me that systems could boost the end user's experience through more than speed to production; systems multiply consistency, usability, and accessibility. And who doesn't want a top-notch, inclusive user experience which the makers can ship more quickly?`, questionTwo: `We stand on the shoulders of giants. I deeply appreciate the former colleagues who have helped me learn and grow, all of the folks who write and speak in the design systems space, and the work of management leaders like [Lara Hogan](https://larahogan.me/), [Camille Fournier](https://twitter.com/skamille), [Sarah Drasner](https://www.engmanagement.dev/), and Caree Youngman. - + The playful, innovative work of my friend [Charlie Gerard](https://charliegerard.dev/projects) never fails to inspire and remind me what humans in tech are capable of creating.`, favoriteTools: `VS Code, React, CSS, axe Accessibility Linter, Netlify, and a big mug`, avatar: 'https://user-images.githubusercontent.com/3902488/153995479-15e25bf5-3f81-4f05-8569-213f668590d4.jpeg', @@ -239,9 +239,9 @@ const teamContent = [ handle: 'langermank', questionOne: `I have a background in design but also love writing code, and design systems are very welcoming to multi-disciplinary folks. I love how design systems bring people together across orgs and create a shared language for collaboration.`, questionTwo: `Medium posts from [Nathan Curtis](https://medium.com/@nathanacurtis) kept me afloat while I worked on my first design system, along with the community in Jina's [Design Systems slack](https://design.systems/). - + I've learned my favorite CSS trickery from [Andy Bell](https://piccalil.li/), [Rachel Andrew](https://rachelandrew.co.uk/css/), [Stephanie Eckles](https://thinkdobecreate.com/), [Sara Soueidan](https://www.sarasoueidan.com/), and [Una](https://una.im/). - + Various design podcasts including [SimpleBits](https://show.simplebits.com/), [Honest Designers](https://www.honestdesigners.com/), [Design Details](https://designdetails.fm/), [Design Better](https://www.designbetter.co/podcast), and [CSS Podcast](https://thecsspodcast.libsyn.com/)`, favoriteTools: `VS Code, Firefox dev tools, CSS, Figma, Pika, Notion`, avatar: 'https://user-images.githubusercontent.com/18661030/133150912-f74c0a6b-2e8a-4547-9d80-872a7d0ff8db.jpg', @@ -421,7 +421,7 @@ const teamContent = [ cssFeature: 'fill: currentColor;', questionOne: `I love organization and lists. I have a lists for things from movies to boba tea orders. I like to bring this into my design work as well, creating components and cohesiveness across platforms to make it easier for people to create great products.`, questionTwo: `When I first began learning about design, I was inspired by the people who contributed back to the community by teaching and opening up to students. Resources like [Students Who Design](https://studentswho.design/) and [Design Details](https://designdetails.fm) helped me figure out how I wanted to make a positive impact in tech. - + More recently, I've been inspired by design agencies and companies that are testing the boundaries of design outside of what is accepted as 'common pratice'. I enjoy seeing unique animation and motion used to convey information, emotion, and storytelling.`, favoriteTools: 'Sketch, Figma, Atom, Dropbox Paper, Twitter, Ping Pong, Ukulele', avatar: 'https://user-images.githubusercontent.com/6846673/59784198-bb703500-9276-11e9-8ec6-a02fc3eb2fc5.jpg', @@ -436,7 +436,7 @@ const teamContent = [ cssFeature: 'fill: currentColor;', questionOne: `Ok, this might sound weird, but I really enjoy looking at UIs. There is something satisfying, seeing a bunch of components getting thrown on a page that fit well together, forming a balanced interface for users to interact with. I also enjoy building UIs and helping others to do the same.`, questionTwo: `Thinking back, seeing the CSS Zen Garden was really inspiring. Also the CSS "demo scene" found in places like [CodePen](https://codepen.io/) is nuts. Admittedly, not always practical, but fun to check out. - + I also got inspired and learned a lot from methodologies like OOCSS, SMACSS, BEM, SUIT and nowadays CSS-in-JS. The "how to organize CSS" is a challenging, but also interesting problem to solve.`, favoriteTools: 'DevTools, Atom, Figma, Sketch, iA Writer, LICEcap, Things, coffee, headphones.', avatar: 'https://user-images.githubusercontent.com/378023/54094782-ad448a00-43e6-11e9-93e0-b5960fa86e89.png', @@ -449,10 +449,10 @@ const teamContent = [ handle: 'jhuashao', cssFeature: 'align-items: center;', questionOne: `I first found out about design systems through my last internship, which was focused on building up a design system for the New York Times. I kept learning more and more about this emerging field, and really started to grow an affinity for it. - + Design Systems seemed to blend all aspects of my interests: Product Design, Front-End Development, Graphic Design, Typography, Illustration, etc. I’m drawn to design systems as it’s a field that welcomes individuals who have too many interests to count, and find themselves at intersections of many different passions. `, questionTwo: `I draw in a lot of inspiration from so many different facets of my life. I’m really fortunate to come from a diverse set of backgrounds to be able to see parallels that emerge from a variety of industries. - + The field of Graphic Design has a tremendous influence on me, and some of the designers and studios I’m inspired by are: [Natasha Jen](https://www.pentagram.com/about/natasha-jen), [Barron Webster](https://barronwebster.com/), [Maxime Buschi](https://www.youtube.com/watch?v=diBifN7qBgw), [Michael Bierut](https://www.pentagram.com/about/michael-bierut), [Eric Hu](http://erichu.info/), [Micah Barrett](http://micahbarrett.design/), [Draw Down Books](https://draw-down.com/), [Wei Huang](https://twitter.com/w__h_?lang=en), [Josh Schaub](http://joshschaub.ch/), [Morcoskey](https://morcoskey.com/), and [David Rudnik](https://davidrudnick.org/). I’ve always been inspired by those who are experimenting at the intersection of design and technology: [Tristan Harris](http://www.tristanharris.com/), [Brad Frost](http://bradfrost.com/), [Studio No-Plans](https://no-plans.com/), [Marie Otsuka](http://motsuka.com/), [Ben Wilkins](https://twitter.com/thatbenlifetho?lang=en), [Jon Gold](https://jon.gold/), [Bret Victor](http://worrydream.com/), and [Chris Novello](http://chrisnovello.com/). I also love typography, and have a lot of admiration for type-designers and foundries: [Colophon Foundry](https://www.colophon-foundry.org/), [Kris Sowersby (Klim Type)](https://klim.co.nz/), [Matthew Carter](https://www.myfonts.com/person/Matthew_Carter/), [Richard Lipton](https://lipton.typenetwork.com/), [Lucas Sharp](http://lucassharp.com/), [Grilli Type](https://www.grillitype.com/), and [James Edmondson (OHnotypeco)](https://ohnotype.co/). There’s so many more people that I’ve learned and drawn inspiration from to mention and praise, so feel free to reach out! I’d love to share and discuss. <3`, favoriteTools: 'VScode, Figma, Adobe Creative Suite, Zero-Sugar Redbull', avatar: 'https://user-images.githubusercontent.com/24916540/47465791-490c8b00-d7a3-11e8-8dc8-9cc968a47b62.jpg', @@ -467,7 +467,7 @@ const teamContent = [ cssFeature: 'align-items: center;', questionOne: `I came into design systems very organically. When I began my career in the agency world, I worked within constraints of branding and style guidelines of our various clients. At the time I didn't fully recognize these guidelines as what we now refer to as design systems. As my career continued to grow I noticed that I began to be far more interested in how various companies/brands packaged the many pieces that made up their brand and/or products. I love how design systems bring together all the pieces in order to unleash endless creativity but still maintain the necessary constraints.`, questionTwo: `I get a lot of my inspiration from the community I've built via Dribbble. A few of my favorites are the dynamic duo that makes of [TheLittleLabs](https://www.thelittlelabs.com/), Camilo and Aradhana, the illustration work by [Enisaurus](https://www.enisaurus.com/), and [Kendrick Kidd](http://www.kendrickkidd.com/). - + When I first started my career, [Frank Chimero](https://frankchimero.com/) was a huge inspiration. His book, [The Shape of Design](https://frankchimero.com/design/the-shape-of-design/), really helped to form my philosophy and approach to problems and how to cultivate a design process. Along with that but not design related, [Jason Fried](https://twitter.com/jasonfried) has been a great inspiration to how I approach work. His book (written alongside David Heinemeier Hansson) [Rework](https://basecamp.com/books/rework) still is the best, no nonsense, business book I've ever read.`, favoriteTools: 'Figma, Atom, Keynote, Bear Notes, Spark Mail, Spotify', avatar: 'https://user-images.githubusercontent.com/10384315/48450021-61941380-e759-11e8-90e0-7b41f6cbb6e8.jpg',