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

ADR: Primer Brand source of truth #40

Open
wants to merge 8 commits into
base: main
Choose a base branch
from
Open

ADR: Primer Brand source of truth #40

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
31aeca0
add ADR for Primer Brand source of truth
rezrah Jun 20, 2022
6aca3f2
add actions
rezrah Jun 20, 2022
f253905
fix typos
rezrah Jun 20, 2022
bf3d30c
add alternative approach
rezrah Jun 20, 2022
d42fd59
grammer
rezrah Jun 20, 2022
769978d
apply pr feedback
rezrah Jun 20, 2022
8764285
tweak wording to address PR feedback
rezrah Jun 28, 2022
119157f
adjust wording
rezrah Jun 29, 2022
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
75 changes: 75 additions & 0 deletions contributor-docs/adrs/adr-001-source-of-truth.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
# ADR 1. Source (and origin) of truth for Primer Brand

Date: 2022-06-19

## Status

Proposed

## Decision

Use design tokens as the source of truth for all design data and logic in Primer Brand.

Tokens (also referred to as Primitives) will serve as a shared data layer between Figma and React Libraries, with Figma providing the origin of said truth.

![diagram of source of truth](https://user-images.githubusercontent.com/13340707/174588236-91fc9ea3-71e8-4780-b5aa-8d74a583e624.jpg)
Copy link

Choose a reason for hiding this comment

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

Can we please also include how we envision that primer/css and view components could be part of this flow?

Copy link
Contributor

Choose a reason for hiding this comment

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

The new primer-primitives design token configuration and values were designed to be used across all Primer frameworks, so PCSS is already part of this process (though it is early days!). Currently, we've configured a "private" bundle for PCSS so we can quietly test some of these tokens before more widely releasing them. The new FormControl CSS is the first to use them, but we'd like to test some of the more base level CSS first before removing the feature flag.

I think for this ADR, it makes sense to have a specific diagram for Primer Brand. I've proposed that we create a workstream next quarter to better establish this flow for all Primer frameworks, which would include much more general/broad process documentation.


## Context

Primer Brand needs to provide an expansive, yet architecturally unified Design System experience for GitHub Site Designers, Site Builders and maintainers.

Its React implementation for example; must optimize for visual and logical parity with its corresponding Figma library.

This is crucial for delivering on the primary customer use-case, which is facilitating an efficient hand-off process between Brand Designers and Marketing Engineers.

Ideally, the React library should operate as the functional render-layer for pre-determined design data, rather than make opinionated decisions of its own. This is to avoid making high-level data decisions too downstream inside an abstraction, which makes synchronization attempts across other mediums more challenging.
Copy link

Choose a reason for hiding this comment

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

Could we try to reword in a more simple/straight-forward way? (So that someone outside of this working group can more easily understand what we're trying to say here)


### Origin of truth

To date, Primer Brand's Figma Library has been the starting point for initial component design and artwork, which is later translated into code. This design-first approach has become increasingly important as we shift-left on accessibility earlier in our design process.
Copy link

@tobiasahlin tobiasahlin Jun 22, 2022 •
edited
Loading

Choose a reason for hiding this comment

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

Not sure if this is true—we've traditionally done a big chunk of work and exploration in code, and the Figma library has also captured what's been originally been defined in code (and in many instances it hasn't been captured in Figma, and the origin of truth then reside in the implementation).

Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
To date, Primer Brand's Figma Library has been the starting point for initial component design and artwork, which is later translated into code. This design-first approach has become increasingly important as we shift-left on accessibility earlier in our design process.
To date, Primer's Figma Library has been the starting point for initial design system component design and artwork, which is later translated into code. This design-first approach has become increasingly important as we shift-left on accessibility earlier in our design process.

Adding this suggestion as a way to make this a little more specific to how Primer develops components.

As we generally shift accessibility left into the design stage across GitHub, and as we begin to create more components in Primer Brand that will will be leveraged in the Site team's designs, there may be opportunities for some brand and marketing work to follow this workflow, too. Of course, there is likely other work - especially the kind that falls outside the purview of the design system, is greenfield, and/or requires a more creative application - that won't work this way.


Figma however, is unsuitable as a source of truth for the code. It lacks the requisite qualities for data persistance and durability. Data retrieval also becomes more expensive as the data is only accessible through an API.

Primer Brand maintainers will - despite this - refer to the Figma Library as the _origin of truth_ for the code, in acknowledgement that design language will rarely - if ever - be established in code first.
Copy link

Choose a reason for hiding this comment

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

Don't think this is true—we're constantly introducing new logic and design tweaks in code, as we realize that the reality is often more complex than what we imagine in Figma.

Copy link
Member

Choose a reason for hiding this comment

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

@tobiasahlin do you think this will be true for the subdomain sites that will heavily leverage Primer Brand in its current form? My assumption is that those sites - the ones often built by agencies - do primarily work this way, but please correct me if I'm wrong 🙏🏻 Those sites are the current deployment target for Primer Brand components as things currently stand.

Copy link

Choose a reason for hiding this comment

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

I think it's totally fair to outline how we want to work here, broadly, but I don't think statements like "in acknowledgement that design language will rarely - if ever - be established in code first" are true for neither .com nor subdomain work (so far). If this is how we want to work, then I think it's better to phrase this something like "The goal for the Figma Library is to act like the origin of truth, …". And rather than denying that design language can be established in code first, I think it's more interesting to talk about how we keep the Figma Library in sync when that happens.

Copy link
Member

Choose a reason for hiding this comment

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

I believe that Primer maintainers treat ADRs as decision documentation which often comes before enforcement, so I think this falls into the "how we want to work" category. Your suggested phrasing change makes sense to me; @rezrah if you agree, perhaps we could codify this change in the PR?

I think it's more interesting to talk about how we keep the Figma Library in sync when that happens.

This seems like a topic worth exploring further. I'd suggest we continue that conversation in a discussion or at an upcoming sync where @ashygee is available to weigh in. We could always add on to this ADR in the future if we determine there's a recommended path for keeping the Figma Library in sync in cases where Figma was not the origin of truth.


This is in contrast to other areas of Primer, where design is occasionally established in code first, or the source of truth is unclear.

Primer Brand attempts to make the creation of data predictable and linear, by hoisting its governance and precedence to Figma while cascading those decisions back down to the code using a persistent data layer.

### Source of truth

To achieve the desired synchronization of React and Figma libraries, a common _data layer_ is shared between them.

Design tokens stored as JSON provide a suitable, framework-agnostic interchange format between Figma and JavaScript-based frameworks like React. They are deterministic and offer performant interfaces for design logic.

We store key design decisions in key-value pairs, the contents of which are inferred initially from Figma designs.

Design tokens also offer us durable and scalable ways to grow the system, as they can be used as a source of truth for a variety of programming languages. Should the need arise to create visual and logical design parity in our ViewComponents, the same design tokens can be used to fan out to those components.

## Alternative approaches

Primer Brand is already operating in the proposed manner, where design language is established in Figma first, then converted to tokens with React implementation shipping last.

As an alternative, we could design and prototype directly in code first and ratify those decisions later in Figma.

Doing this creates several problems, however:

- Brand art direction is usually defined and governed by the Brand Design team. They work directly with Figma as opposed to code. Achieving sign-off through PRs could be logistically expensive and inconvenient.
Copy link

@tobiasahlin tobiasahlin Jun 22, 2022 •
edited
Loading

Choose a reason for hiding this comment

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

Again, not really how our process looks like for brand at large.

Copy link

Choose a reason for hiding this comment

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

@tobiasahlin yes that's correct that this is not the process within all of brand. In this section, I believe what we are trying to say is that the design (and/or art direction) for a page/site is typically defined and governed by the Site Design team, who all work predominately in Figma first. While there are changes that happen post-initial design, we are recognizing here that continually iterating on design only in code could potentially be expensive and inconvenient for all contributors and stakeholders working on a project.

Copy link

@tobiasahlin tobiasahlin Jul 26, 2022 •
edited
Loading

Choose a reason for hiding this comment

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

@ashygee what you're saying is more nuanced, but I'm commenting on:

They work directly with Figma as opposed to code.

I think we can add more nuance here—that's not how the process looks like. Some parts a design is also easier to work with through PRs and code (e.g. animation and interactivity), so saying that we don't work with code or that code is more expensive than Figma is just not true.

- Ideation and experimental artwork is often produced by Designers in Figma first due to ease-of-use and fewer barriers to entry.
- Designing in code is not inclusive of team skill-sets and preferences, where designers may be unable to operate at peak efficiency in code, and vice-versa for engineers.
- Shifting-left on accessibility means bringing audits, reviews and recommendations into the design phase as early as possible. Primer already has a distinction between `A11Y Design review` and `A11Y Eng reviews`.
- Design becomes a side-effect of Primer Brand, rather than a first-class citizen.
Copy link

Choose a reason for hiding this comment

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

I don't really understand what we're saying here. Are we saying that if we prototype design in code, design becomes a side-effect of Primer Brand? How? What does that mean?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

This line is referring to the challenges of keeping Figma libraries in sync with code, where framework implementations are far more up-to-date and ahead of the Figma components. In some cases across Primer, we've seen entire components designed in React first without a corresponding Figma component immediately available. While this is good for unblocking engineering effort on those components, our System Designers aren't able to influence the design process early enough, particularly around areas like accessibility.

My understanding of the customer use-case here is that we would want the Primer Brand Figma library components to be accurately represented in code, in order to make the handoff process efficient between site designers and eng. It's always going to be an uphill challenge if the design library is always catching up - and reacting - to code however. Does that clarify @tobiasahlin? Hopefully not made it even more confusing 😅.

Copy link

Choose a reason for hiding this comment

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

I totally understand that "catching up" to code can be challenging, but I don't follow how we come to the conclusion that we want to avoid learning and exploring through code just because it's challenging for Figma to catch up. I think interactivity and real-world scenarios are tremendously valuable, and Figma can't really fully capture the problem space that we're operating within. I feel like we could use language (and a process) that focuses more on achieving a synergy between Figma and code, rather turning away from one or the other.

Copy link
Member

Choose a reason for hiding this comment

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

I think interactivity and real-world scenarios are tremendously valuable

+1000 to this.

It's not my impression that this ADR suggests that prototyping or exploring real-world scenarios in code is an anti-pattern to how we work. @tobiasahlin is that the message that you took away? If so, perhaps we can take another stab at the wording.

- Additional overhead for designers to review and sign off design decions, and similarly more work required for engineers to refactor based on said feedback.
Copy link

Choose a reason for hiding this comment

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

I don't think we need to stay less in sync if design logic flows from Figma to code, or the reverse. This feels like something we can't, and don't want to, avoid.


## Consequences

- Primer Brand maintainers will encourage all new and/or major design decisions to be explored and ratified in Figma or Design Tokens before they are applied to the Framework code.
Copy link

Choose a reason for hiding this comment

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

All again here seems broad, and this isn't really aligned with how we work, how we've worked, and not sure if we want to work like this. I'm also not sure how it's really related to this ADR (how we store and distribute tokens).

Copy link
Member

Choose a reason for hiding this comment

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

Suggested change
- Primer Brand maintainers will encourage all new and/or major design decisions to be explored and ratified in Figma or Design Tokens before they are applied to the Framework code.
- Primer Brand maintainers will encourage new and/or major design decisions that are meant to be reusable aspects of the brand system to be explored and ratified in Figma or Design Tokens before they are applied to the Framework code.


- Figma may describe the initial vision or design strategy, but design tokens should be used in the longer term to synchronize design data between mediums.

- A dedicated Figma plugin will be required to allow Figma users to interface with the source of truth. The React library is co-located to the tokens and already compatible with the interchange format.

## Actions

- [ ] Configure the [Figma Tokens](https://www.figma.com/community/plugin/843461159747178978/Figma-Tokens) plugin to interface and synchronize with the source of truth.
- [ ] Write contribution guidelines for the source of truth.
31 changes: 31 additions & 0 deletions contributor-docs/adrs/adr-template.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
<!-- Complete the following sections: -->
Copy link
Contributor

Choose a reason for hiding this comment

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

This is awesome! Thank you 😄

Copy link
Member

Choose a reason for hiding this comment

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

Thanks for adding this! 🙌🏻


# Title

## Status

<!-- What is the status of this ADR?

Choose one of the following: -->

- Proposed
- Accepted {date}
- Rejected {date}
- Deprecated {date}
- Superseded by {adr_id}

## Decision

<!-- What is the change that you're proposing and/or doing? -->

## Context

<!-- What is the situation or issue motivating this decision? -->

## Alternative approaches

<!-- What are the alternative approaches you have considered, that justify and validate your recommendation? -->

## Consequences

<!-- What becomes easier or more difficult to do because of this change? -->