diff --git a/content/foundations/color.mdx b/content/foundations/color.mdx index 826f931a9..0c5e0b513 100644 --- a/content/foundations/color.mdx +++ b/content/foundations/color.mdx @@ -17,8 +17,8 @@ import {Box, Heading} from '@primer/react' GitHub's UI offers a variety of different color modes. Every pattern in Primer is built to work across all color modes out of the box. -When designing product interfaces in Figma, we recommend using light mode. This is best because the Primer Figma components are only available in light mode. -To preview your work in other modes, use the [Figma color mode plugin](https://www.figma.com/community/plugin/992128487074360945/Change-Color-Mode). +When designing product interfaces in Figma, we recommend using *light mode* or *dark mode*. This is best because the Primer Web Figma library provides components and tokens in those two modes. +You can learn more about using design tokens in Figma in our [Figma guidelines](../guides/figma/getting-started#styles-and-variables). ## How to use color for product UI diff --git a/content/guides/figma/getting-started.mdx b/content/guides/figma/getting-started.mdx index 28cca76e0..55c667363 100644 --- a/content/guides/figma/getting-started.mdx +++ b/content/guides/figma/getting-started.mdx @@ -1,14 +1,15 @@ --- title: Getting started +description: Principles, standards, and usage guidelines for designing GitHub interfaces with Figma --- import {LinkExternalIcon} from '@primer/octicons-react' -## What are Primer Figma libraries? -The Primer Figma libraries contain UI components and design tokens (styles) that our teams at GitHub use to design GitHub. The components contained within Primer match what is available for developers in Primer React Components, Primer ViewComponents, and Primer CSS. +## What are Figma libraries? +Figma libraries contain UI components and design tokens (`variables` and `styles`). At GitHub we have one product design system library called _Primer Web_ that our teams at GitHub use to design GitHub. The components contained within Primer match what is available for developers in Primer React Components, Primer ViewComponents, and Primer CSS. ## Installation To use a library in Figma enable (install) it from the **assets** tab (`option` + `2`). -You can also directly open the *team library* view via the command palette or with the shortcut `option` + `cmd` + `o`. +You can also directly open the _team library_ view via the command palette or with the shortcut `option` + `cmd` + `o`. - + Screenshot showing the library overview in figma +### Styles and variables -## Understanding styles -Figma libraries like `Primer Primitives` install styles for you to use. In contrast to *local styles* they don't show up in the sidebar. -However once you open a selection to choose a color style, text style, etc. you will see the styles from team libraries as well. +Styles and variables are two ways to use [Primer Primitives](https://github.com/primer/primitives) (design tokens) in Figma. +Our goal is to move everything over to variables, but at the moment only color and size tokens are supported. This is why we still provide text and shadow tokens using styles. -To quickly find a style you can use the search box. E.g. use `accent` to bring up all accent colors. +### Understanding styles +Figma libraries like _Primer Web_ provide styles for you to use. In contrast to local styles, styles from a library don't show up in the sidebar. However, once you open a selection to choose a `text style` or `shadow style` you will see the styles from team libraries as well. - +Available styles: +- text styles +- shadow styles + +To quickly find a style you can use the search box. E.g. search for `body` to bring up all body text styles as well as related ones. + + Screenshot showing the style selector in figma -Learn more about Figma styles +### Understanding variables (primitives) +Our Figma libraries use `variables` to represent design tokens. Variables from a library don't show up in the sidebar. +However once you open a selection to choose a color, or size, etc. you will see the variables from team library as well. + +To use the `variables` you need to enable the `Primer Web` library in your file. + +Available variables: +- color variables +- size variables + +To quickly find a `variable` you can use the search box. E.g. use `accent` to bring up all accent colors or `fgColor` to find all text related colors. + + + Screenshot showing the color variable panel in figma + + +#### Scope +Variables in Figma are _"scoped"_, meaning they can only be used in specific situations. Currently Figma offers the following scopes for color variables: `Frame fill`, `Shape fill`, `Text fill` , `Stroke`. + +For you this means that if you want to create a border using a `borderColor` you need to use a `stroke` (path tool) or a `border` around a `frame` or `shape`. Similarly `fgColors` can not be used for borders and `bgColors` can only be used for `frame fills` and `shape fills`. + +**Note:** There are two exceptions to this rule. +1. Some `bgColors` are available for `borders` and `strokes` because we use them when placing things like notification dots on top of elements like an avatar. +2. `fgColors` are also available for `shape fill`. This is nessary because icons are shapes, but use `fgColors` + + + Screenshot showing the color variable panel with specific scopes in figma + + +Learn more about Figma variables + +### Variables vs. styles +Variables and styles are fairly similar, but there are some key differences. You can identify a color variables by the squared color representation and a style by the round one. + +**Styles** can be used for color, grids and shadows. The can have multiple colors, pictures or gradients combined in one style and they can be replaced using the style swap utility. However they can not be nested. + +**Variables** are more similar to design tokens in that they can only have a single raw value, either a color, string or number. However they can reference another valid variable e.g. the variable `fgColor/danger` can reference `base/color/red/4`. This makes variables a better choice to represent design tokens. ## Understanding components At GitHub, we have created a [set of guidelines](https://github.com/primer/figma/blob/main/docs/authoring-components.md) that contributors and maintainers can reference when creating and updating components. @@ -51,6 +103,22 @@ Components in our libraries have been built to be easy to understand for consume ### Variants and component properties To make components dynamic, we favor [component properties ](https://help.figma.com/hc/en-us/articles/5579474826519-Explore-component-properties) over nesting, so users don't have to override parts of a component manually. -Whenever possible use components as they are without *detaching*. +Whenever possible use components as they are without _detaching_. Learn more about Figma components + +## Using variable themes + +Primer Web provides _light mode_ and _dark mode_ using figma `variables`. This means you don't need a plugin to change between modes. Simply select any `frame` that uses `variables` or components with `variables`. Select the mode from the dropdown in the _layer_ section in the right sidebar + + + + + +### Video introduction to primer web variables and modes / themes (GitHub staff only) +