ADR: Primer Brand source of truth #40
There are no files selected for viewing
| 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 reusable design data and logic in Primer Brand. | ||||||
|
|
||||||
| Tokens (also referred to as [Primitives](https://github.com/primer/primitives)) will serve as a shared data layer between Figma and React Libraries, with Figma providing the origin of said truth. | ||||||
|
|
||||||
|  | ||||||
|
|
||||||
| ## 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. | ||||||
|
|
||||||
| 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.
Suggested change
typo :) |
||||||
|
|
||||||
| ### Origin of truth | ||||||
|
|
||||||
| To date, Primer's Figma Library has been the starting point for design system component ideation 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. | ||||||
|
|
||||||
| 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?
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. | ||||||
lesliecdubs marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
|
||||||
| 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. | ||||||
|
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:
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.
+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. | ||||||
|
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 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. | ||||||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,31 @@ | ||
| <!-- Complete the following sections: --> | ||
|
There was a problem hiding this comment. This is awesome! Thank you 😄 |
||
|
|
||
| # 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? --> | ||
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The new
primer-primitivesdesign 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 newFormControlCSS 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.