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.

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

Conversation

rezrah
Copy link
Collaborator

@rezrah rezrah commented Jun 20, 2022

Primer Brand has matured significantly in Q4, so it's important to codify aspects of its data governance - specifically its source of truth - for our users and future maintainers.

This PR attempts to describe the relationship between Figma, design tokens and the resulting React component library.

Read the ADR here:

https://github.com/primer/react-brand/blob/rezrah/adr-source-of-truth/contributor-docs/adrs/adr-001-source-of-truth.md

Any questions? please ask away in the comments. All feedback appreciated.

@changeset-bot
Copy link

changeset-bot bot commented Jun 20, 2022

⚠️ No Changeset found

Latest commit: 119157f

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@rezrah rezrah changed the title add ADR for Primer Brand source of truth ADR: Primer Brand source of truth Jun 20, 2022
@rezrah rezrah added the brand label Jun 20, 2022
@rezrah rezrah temporarily deployed to github-pages June 20, 2022 10:58 Inactive
@rezrah rezrah temporarily deployed to github-pages June 20, 2022 11:13 Inactive
@rezrah rezrah temporarily deployed to github-pages June 20, 2022 13:43 Inactive
@rezrah rezrah temporarily deployed to github-pages June 20, 2022 13:50 Inactive
Copy link
Contributor

@langermank langermank left a comment

Choose a reason for hiding this comment

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

Well done, I personally like this direction! Interested to hear from the rest of the team 🙂

@@ -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! 🙌🏻

Copy link

@ashygee ashygee left a comment

Choose a reason for hiding this comment

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

I really like this @rezrah, this direction seems to be what we've all been talking about as the ideal process for a while so I'm happy to see it codified into a concrete decision.

@rezrah rezrah temporarily deployed to github-pages June 20, 2022 18:42 Inactive
@ajashams
Copy link
Collaborator

@ashygee @rezrah - This line under Alternative Approaches is the only thing that gives me pause 🤔 .

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.

It's unclear to me what we define as tokens as it feels quite broad. I'm wondering how we will handle sub-brands vs our core brand, and various themes as we define them in the brand (not necessarily as defined in systems or engineering). Can we provide more clarity on this and outline some examples? It's hard to give a thumbs up without it.

@ashygee ashygee requested a review from tobiasahlin June 21, 2022 16:19
@ajashams
Copy link
Collaborator

ajashams commented Jun 21, 2022

Design Approval ✅

After a clarifying conversation with @rezrah and @ashygee, here's how I understand this document:

  • Design tokens will be the source of truth for styles across design and code
  • This ADR does not define the design tokens, it merely proposes that we use them as a source of truth
  • Gloss Web's current styles will inform these design tokens. This is because brand is typically defining styles in Figma and is the most accurate representation of preferred changes.

All of this sounds good to me! My previous comment was in reference to how we name design tokens, but this will be explored once we get agreement on using design tokens. 👍 from me.

Copy link
Contributor

@colebemis colebemis left a comment

Choose a reason for hiding this comment

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

Love it 💖

@rezrah rezrah requested a review from ajashams June 21, 2022 18:23
Copy link

@tobiasahlin tobiasahlin left a comment

Choose a reason for hiding this comment

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

Left some thoughts! I wonder if we can simplify this to focus more on just the flow of design tokens/data, rather than talking about how we design, code and build marketing pages, where I feel like this document is not aligned with how we actually work in brand at large.

I read the core message here as "we should have design tokens that live outside of Figma, and should be pulled into Figma, even if Figma is often, but not always, the origin of truth"—which I think is fair. To that extent, many aspects of the design system has evolved in code as we've put the system to test, and that work needs to be captured somehow (it's currently not fully captured in Figma).


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)

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.


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.

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

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.

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.

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.


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

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

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.

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

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.

- 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.
- Additional overhead for designers to review and sign off design decions, and similarly more work required for engineers to refactor based on said feedback.

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.

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.

Copy link
Member

@lesliecdubs lesliecdubs left a comment

Choose a reason for hiding this comment

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

Left a few thoughts and suggestions for consideration. Thanks for putting this together 🙏🏻


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


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

@@ -0,0 +1,31 @@
<!-- Complete the following sections: -->
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! 🙌🏻

@rezrah rezrah temporarily deployed to github-pages June 28, 2022 11:24 Inactive
@lesliecdubs lesliecdubs self-requested a review June 28, 2022 20:22
@lesliecdubs
Copy link
Member

Oops, didn't mean to re-request my review. Please ping me here if/when you'd like me to take another pass. Thanks!

@rezrah rezrah temporarily deployed to github-pages June 29, 2022 14:03 Inactive
@@ -22,7 +22,7 @@ Its React implementation for example, must optimize for visual and logical parit

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.
The React components are mostly responsible for managing application state, behavior and rendering to the DOM. The components aren't opinionated about design decisions. This is by-design, as CSS modules are used as the styling later that React components interface with. This helps to avoid making design decisions too downstream inside framework-specific code. Hoisting design decisions out of framework-specific code makes integration with tooling like Figma easier and more efficient.
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
The React components are mostly responsible for managing application state, behavior and rendering to the DOM. The components aren't opinionated about design decisions. This is by-design, as CSS modules are used as the styling later that React components interface with. This helps to avoid making design decisions too downstream inside framework-specific code. Hoisting design decisions out of framework-specific code makes integration with tooling like Figma easier and more efficient.
The React components are mostly responsible for managing application state, behavior and rendering to the DOM. The components aren't opinionated about design decisions. This is by-design, as CSS modules are used as the styling layer that React components interface with. This helps to avoid making design decisions too downstream inside framework-specific code. Hoisting design decisions out of framework-specific code makes integration with tooling like Figma easier and more efficient.

typo :)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

8 participants