[WIP] Cross-platform components for web/Figma/Sketch/React Native

[macintoshhelper]

Don't merge yet

This exists mostly as a proof-of-concept for now, to go together with the proposal issue #744 🙂. I'd love feedback on it to see if this something worth working on further and that is likely to be merged.

Abstract

Implements cross-platform resolving for styled-components that allows this project to be imported into react-dom, react-native, react-sketchapp and react-figma projects.

This is a bit of a refactor that adds custom platform handling logic across the codebase, using react-primitives. Webpack aliasing in the Figma/(other native platforms) entrypoint is used where possible to keep the project friendly for web developers, and not use react-native-web for web to maintain styled-components SSR support and keep bundle sizes low.

Webpack resolving examples:

• import styled from 'styled-components' -> import styled from 'styled-components/primitives' on native platforms only
• styled.button -> styled.View on native platforms only

Quote from https://github.blog/2018-04-12-driving-changes-from-designs/#excited-about-the-future

The upcoming Figma write API will allow us to maintain our component library in code and export those as Figma components. Using a team library we can publish updates and make them available to the GitHub Product Design Team to use in their design mockups and prototypes.

Closes #744

The goal

The main idea of this is to allow the same Primer components codebase to be able to automatically generate Figma and Sketch component libraries (and styleguides), with react-figma and react-sketchapp respectively. As an added bonus, the components can be used in React Native (or ReactXP potentially) codebases.

CI could also be used to automatically generate Figma/Sketch style-guides using a library like @elemental-design/style-guide, taking the styled-system theme.js and components as an input and outputting cross-platform Figma/Sketch/storybook/Gatsby style-guide documentation. This could be integrated inside of Doctocat.

So, as an example, a new primer/style-guide repo could be created, with cross-platform compatible markdown docs migrated over to there, and it'll accept a theme object and components list as inputs, and can be used as a dependency in Doctocat or the Figma entrypoint.

Platform-specific page entrypoint:

import { Colors } from '@primer/style-guide';
import { theme } from '@primer/components';

// react-figma/gatsby/react-sketchapp page:
export default () => (
  <Colors colors={theme.colors} />
);

primer/style-guide – docs/buttons.md file, that can be imported into Doctocat, Figma style-guide jsx, etc

## Buttons

Description of how buttons should be used here. Lorem ipsum.

<ButtonsGroup>
  <Button>Button</Button>
  <ButtonPrimary>Primary Button</ButtonPrimary>
</ButtonsGroup>

Screenshots

TODO

• Cross-platform components:
  • Avatar
  • AvatarStack
  • Buttons
  • BorderBox
  • Box
  • BranchName
  • ...
• Cross-platform CSS shadow implementation. Pseudo-code example below:

  •    const makeShadow = (shadow) => {
         switch(Platform.OS) {
           case 'web': { return `box-shadow: ${shadow};` }
           case 'sketch':
           case 'figma':
           case 'ios': {
             const shadows = parseShadow(shadow({}));
             return `shadow-color: ${shadows[0].color}
             // ...
             `;
           }
           case 'android': {
             return `elevation: ${calculateElevationIntFromTheme(shadow({}))
           }
         }
    
      const Button = styled.button`${makeShadow(get('button.default.elevation'))}`

Merge checklist

• Added or updated TypeScript definitions (index.d.ts) if necessary
• Added/updated tests
• Added/updated documentation
• Tested in Chrome
• Tested in Firefox
• Tested in Safari
• Tested in Edge

(will do the above if/once it's past proposal stage)

Take a look at the What we look for in reviews section of the contributing guidelines for more information on how we review PRs.

[vercel]

This pull request is being automatically deployed with ZEIT Now (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://zeit.co/primer/primer-components/p687ontbv
✅ Preview: https://primer-component-git-fork-macintoshhelper-feat-figma-pri-ec1252.primer.now.sh

[emplums]

Hey @macintoshhelper! This is a really neat idea & thanks so much for doing this work and opening a PR! Unfortunately, we already have a Figma component library that we're using across product design as a single source of truth and don't have plans for using our React code as that source of truth in the near future.

Because this approach would create a bit more complexity in our styled components code and the Primer core team would need to maintain that across all our components, it don't think it makes sense to go forward with this approach for now. Additionally, we aren't yet using our React components cross platform, but if/when we do, I'd love to circle back on this 🙌

[macintoshhelper]

Hey @macintoshhelper! This is a really neat idea & thanks so much for doing this work and opening a PR! Unfortunately, we already have a Figma component library that we're using across product design as a single source of truth and don't have plans for using our React code as that source of truth in the near future.

Hi @emplums , thanks! Yes, I appreciate that this is a large task and would require a big effort to use the new component library internally, especially in terms of migration of existing design files/assets, and is unlikely to fit the current design processes/workflow. My main goal was to float the idea and explore the feasibility of migrating an existing codebase to render straight to design, and I'm surprised how close the Figma output is to the web design for atomic components like buttons, relative to the code changes needed 🙂.

Because this approach would create a bit more complexity in our styled components code and the Primer core team would need to maintain that across all our components, it don't think it makes sense to go forward with this approach for now. Additionally, we aren't yet using our React components cross platform, but if/when we do, I'd love to circle back on this 🙌

Yes, I agree that there'd be extra maintenance for the styled components code, especially as native platforms don't have CSS inheritance, pseudo selectors, etc, so this functionality has to be polyfilled in a manner which would require onboarding for all devs. I think the complexity can be balanced out by the benefits of having a very component-driven, functional/test-driven and side-effect free process, but this would need to be part of a long-term effort and shift in technical direction, and makes more sense to invest in if using react-native or React style Kotlin/Swift.

I'll carry on the work at https://github.com/elemental-design/ as a community effort, and will move the fork over to https://github.com/elemental-design/primer-components , and will work on abstracting as much of the work as I can into libraries (e.g. box-shadow to multi-platform/Figma shadows), which may be useful should this be something you'd like to explore in the future, or use incrementally for individual parts of the Figma style-guide/library. I'm working on an mdx to Figma library too, which would be able to parse https://github.com/primer/components/blob/master/docs/content/Buttons.md to a Figma document.

Do you have any thoughts on having the fork showcased for community/third party use of this library? I've seen that there seems to be interest in having publicly available Primer Figma assets, so maybe having an unofficial community-maintained Figma style-guide and component library using this fork would be interesting?