Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updating Figma content to include variables #653

Merged
merged 5 commits into from
Nov 8, 2023
Merged

Updating Figma content to include variables #653

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
6837f15
adding details about variables
lukasoppermann Nov 3, 2023
adc4660
update to trigger
lukasoppermann Nov 6, 2023
9893313
Update content/guides/figma/getting-started.mdx
lukasoppermann Nov 7, 2023
01e59a6
Update content/guides/figma/getting-started.mdx
lukasoppermann Nov 8, 2023
46f1cb0
Update getting-started.mdx
lukasoppermann Nov 8, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions content/foundations/color.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
98 changes: 83 additions & 15 deletions content/guides/figma/getting-started.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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`.

<ImageBox caption="Navigate to the assets tab in the left sidebar and press the book icon to open the libraries overview.">
<img
Expand All @@ -18,30 +19,81 @@ You can also directly open the *team library* view via the command palette or wi
/>
</ImageBox>

<ImageBox caption="Enable all libraries you need in your file.">
<ImageBox caption="Enable Primer Web and all other libraries you need in your file.">
<img
width="443"
width="508"
alt="Screenshot showing the library overview in figma"
src="https://user-images.githubusercontent.com/813754/221527802-76638b6b-be81-4c87-b3e8-63d543537a9c.png"
src="https://github.com/primer/react/assets/813754/675eb97e-479d-47db-bd29-f10c136f586a"
/>
</ImageBox>

### 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.

<ImageBox caption="Color style selector and color style selector with search for 'accent'">
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.

<ImageBox caption="Text style selector with search for 'body'">
<img
width="443"
width="261"
alt="Screenshot showing the style selector in figma"
src="https://user-images.githubusercontent.com/813754/221531315-605cba02-de29-4834-a01b-ef8dc391fe21.png"
src="https://github.com/primer/react/assets/813754/4537b229-a663-499d-b0f0-d6be0d9fdadb"
/>
</ImageBox>

<a href="https://help.figma.com/hc/en-us/articles/360039238753-Styles-in-Figma">Learn more about Figma styles <LinkExternalIcon /></a>
### 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.

<ImageBox caption="Color variables panel and panel with a search for 'fgCo'">
<img
width="509"
alt="Screenshot showing the color variable panel in figma"
src="https://github.com/primer/design/assets/813754/34835137-cc62-45ce-9abf-3573089eb278"
/>
</ImageBox>

#### 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`

<ImageBox caption="Color variable panel with scope 'backgroundColor' and 'borderColor'">
<img
width="700"
alt="Screenshot showing the color variable panel with specific scopes in figma"
src="https://github.com/primer/design/assets/813754/a0e01b5c-74d8-4962-b6c2-888fb951c70f"
/>
</ImageBox>

<a href="https://help.figma.com/hc/en-us/sections/14506605769879-Variables">Learn more about Figma variables <LinkExternalIcon /></a>

### 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.
Expand All @@ -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 <LinkExternalIcon />](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_.

<a href="https://help.figma.com/hc/en-us/articles/360038662654-Guide-to-components-in-Figma">Learn more about Figma components <LinkExternalIcon /></a>

## 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 <svg class="svg" xmlns="http://www.w3.org/2000/svg" width="14" height="12" viewBox="0 0 14 12"><path fill="#000" fill-opacity="1" fill-rule="evenodd" d="m5 1.381-4 2.31v4.618l4 2.31 4-2.31V3.691L5 1.38zm5 1.732L5 .227 0 3.113v5.774l5 2.887 5-2.887V3.113zm3 5.196-5 2.887 1 .578 5-2.887V3.113L9 .227 8 .804l5 2.887v4.618zM6 6c0 .552-.448 1-1 1-.552 0-1-.448-1-1 0-.552.448-1 1-1 .552 0 1 .448 1 1z"></path></svg> in the _layer_ section in the right sidebar

<ImageBox caption="Switching the variable mode changes all nested items">
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I love little snippets. 😍

The GIF's quality isn't great, but it might be hard to fix unless we change it to a video. We should see what the team thinks, but I think we've talked about using videos instead of GIFs because they're easier for everyone to use.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1 for using a video instead of a GIF here

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How can I add an autoplaying video?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's a component called CustomVideoPlayer. It accepts all the same props as the HTML tag, so you can pass autoplay.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great, thanks, used that now. It does not support muted though, right?

<CustomVideoPlayer
width="804"
loop
autoplay
src="https://github.com/primer/design/assets/813754/a58ce41e-e4de-4267-9219-4d180350a8f0"
/>
</ImageBox>

### Video introduction to primer web variables and modes / themes (GitHub staff only)
<a href="https://github.rewatch.com/video/qvryg0cscoowmpyx-figma-primer-web-update-to-figma-variables"><img src="https://thumbnails.rewatch.com/thumbs/qvryg0cscoowmpyx?fm=jpg&p=true&q=100" /></a>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note: Remember that this is only for internal use. As I mentioned before, we need to make it clear that it's for internal purposes. If we decide to make the Figma library public in the future, maybe we could download the video and host it on a public URL?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is publicly available forever already. 😉