ADR: Primer Brand source of truth #40
Conversation
|
rezrah
changed the title
| @@ -0,0 +1,31 @@ | |||
| <!-- Complete the following sections: --> | |||
There was a problem hiding this comment.
This is awesome! Thank you 😄
|
@ashygee @rezrah - This line under Alternative Approaches is the only thing that gives me pause 🤔 .
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. |
Design Approval ✅After a clarifying conversation with @rezrah and @ashygee, here's how I understand this document:
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. |
There was a problem hiding this comment.
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. | ||
|
|
||
|  |
There was a problem hiding this comment.
Can we please also include how we envision that primer/css and view components could be part of this flow?
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
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).
There was a problem hiding this comment.
| 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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
@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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
Again, not really how our process looks like for brand at large.
There was a problem hiding this comment.
@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.
There was a problem hiding this comment.
@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. |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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 😅.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
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).
There was a problem hiding this comment.
| - 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. |
|
|
||
| ### 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. |
There was a problem hiding this comment.
| 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. |
There was a problem hiding this comment.
@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. |
There was a problem hiding this comment.
| - 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: --> | |||
|
Oops, didn't mean to re-request my review. Please ping me here if/when you'd like me to take another pass. Thanks! |
| @@ -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. | |||
There was a problem hiding this comment.
| 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 :)
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.