shopify / foundational-design-system-proto

A prototype for a foundational design system at Shopify

Shopify Design Foundations

About this repo | Projects | How to use this repo | Technical details | Contribute to our explorations | Resources

---

About this repo

The experience platform for Shopify. This repository is focused on centralizing foundational design system resources.

Current status	Owner	Help
paused	@polaris-team	#polaris

Projects

A public version of our Github Project will be coming soon!

Development

Make sure Git and Node.js are installed on your computer, then run the following commands in your terminal to get started:

$ git clone https://github.com/Shopify/foundational-design-system-proto.git    # git clone repository
$ cd foundational-design-system-proto                                          # access the files
$ npm install                                                                  # install dependencies
$ npm run dev                                                                  # run locally

Technical details

As we continue to iterate and evolve, these technologies are subject to change. Currently, the foundations are built using the following technologies as part of our React TypeScript stack:

• Sprinkles, a CSS framework for vanilla-extract
• vanilla-extract, a CSS-in-JS library
• ViteJS, a frontend build tool

For questions about our tech stack, go to #polaris

Contribute to our explorations

We'd love to hear what you think. Start a conversation in Github Discussions!

---

Resources

Documentation

• Design tokens
• React components

NPM packages

@shopify/layout-experimental

An NPM package of experimental React components for layout, including abstractions for flexbox and grid, built with Vanilla Extract and Sprinkles.

Install locally

1. Add the dependency:

NPM

npm install @shopify/layout-experimental

Yarn

yarn add @shopify/layout-experimental

2. Import the foundation styles at the base of your app:

import '@shopify/layout-experimental/dist/style.css';

3. Read the component API documentation

Explore the sandbox

We have created a sandbox utilizing the experimental release of our foundational layout components: Box, Grid, Flex, and more. Check it out to see examples of how the components can be used and try them out yourself!

foundational-design-system-proto's Issues

Research layout approaches and document approach in discussion

Discussion started Shopify/polaris#116

Add a CLA for external contributions

Publish "Problems with Sass" blog post

Problems with Sass at Scale

Box properties

Discussed in Shopify/polaris#49

^{Originally posted by kyledurand June 21, 2021}
Right now we have margin as the only available box property. How deep down the properties rabbit hole do we want to go?

Should we add flex / grid if we have flex / grid element components? I'm thinking these can be used inside of the Box component to create layouts.

What are some sensible defaults for this component?

Possibilities:

Box does everything: spacing, flex, and grid properties

• This makes for less markup
• Potentially more confusing for consumers. Will they find this component intuitive? Will they intrinsically reach for the box component to build layouts? This makes things even more confusing when introducing Flex and Grid components.

Box does wrapper like things

• Think Text container
• Margin, padding, text align, ??

Purpose

The current use-case of Box is for building layout. With its current functionality, it can be used to apply margin and padding directly to an element.

The purpose of Box could be expanded to be a more flexible low-level primitive. This would function as a bridge between HTML elements and our design tokens. The Box could be a simple extension of an HTML element (div by default) that provides access to themed atomic styles using a prop-based interface.

Deploy website to polaris.shopify.com

Form a strong opinion and strategy for what we want Polaris to be

Follow up to https://github.com/Shopify/alpha.polaris.shopify.com/issues/259

As we start to build out the foundation and work with local system teams, we need to form and share a strong opinion and strategy of what we want Polaris to be so consuming teams can start to work with that in mind.

Remove dev commands from README.md

This repository is for anyone and dev has heavy shopify context. We should write the Development quick start guide in a way that people who don't use dev can access it.

Update elements folder to components

Figma onboarding review

There is a new Figma onboarding experience that is about to be published as part of the UX onboarding path. Let's review the experience for any Polaris-related content and see if it meets our needs.

Next Steps:

• audit resource and catalog feedback
• figure out who will own maintenance on the resource and provide feedback

Scaffold a monorepo tool analysis sheet

(Similar to the CSS-in-JS spreadsheet to help with decision making, reference the needs/goals outlined)

Research the tools in the monorepo analysis sheet

Analysis sheet

Create default tokens for spacing scale

New discussion on removing sass

Explore alternative styling solutions for Polaris foundations

Styling Explorations

Simplify spacing function

I wonder the value of this function. It might be more human readable to just include the px then wrapping everything in px().

const px = (value: number) => `${value}px`;

Originally posted by @alex-page in Shopify/polaris#102 (comment)

Add analytics to site

Update links to polaris.shopify.com in onboarding documentation

What design tokens do we need?

Which design elements do we need to represent in our system?

Things like:

• spacing
• color
• typography
• animations
• object styles
  • Rounding
  • Border width
  • Drop shadow

Design tokens are all the values needed to construct and maintain a design system — spacing, color, typography, object styles, animation, etc. — represented as data. These can represent anything defined by design: a color as a RGB value, an opacity as a number, an animation ease as Bezier coordinates. They’re used in place of hard-coded values in order to ensure flexibility and unity across all product experiences.

Update spacing approach

Discussion for spacing scale

Research breakpoints

Shopify/polaris#94

Spacing curve should always be created with some initial values that do not match the `4px` scale

This came up as a point of discussion from a spacing PR. We came to the conclusion that we need smaller increments at the beginning of the spacing scale that break out of the 4px increments.

Example:

   0: `${unit} * 0`,
  .25: `${unit} * .25`,
  .5: `${unit} * .5`,
  .75: `${unit} * .5`,

---

I think the spacing curve should always be created with some initial values that do not match the 4px scale. Would love to know peoples thoughts?

  0: 0,
  1: px(1),
  0.5: px(2),

Originally posted by @alex-page in Shopify/polaris#102 (comment)

Create Link foundational component for landing page

Creating a foundational link component to be used in the landing page and future endeavours

As seen on the landing page component shopping list: Shopify/polaris#50

Front end development onboarding update

The RnD Education team has kicked off a project called Structured onboarding for engineers, which aims to increase the effectiveness of engineering onboarding while decreasing the load on leads. As part of this project, the team is looking at front-end development onboarding, which includes Polaris-related components.

Let's support this initiative by helping to audit and update the existing content, and if needed, produce new content that effectively teaches our new hires about building front-end interfaces using our system of systems, Polaris.

Add a license to to the Readme

Set up the repo for open source

To learn

• https://development.shopify.io/engineering/overview/approach/open_source
• Follow the GitHub community instructions
• Everyone should read through https://opensource.guide

To do

• Shopify/polaris#38
• Shopify/polaris#97
• Shopify/polaris#101

Deploy website to polaris.shopifycloud.com

Revisit "composed" component naming

Shopify/polaris#90

shopify/polaris Readme.md file following template

https://github.com/Shopify/development-docs/wiki/README.md-Template

[Week 2] Global Modal

Working base branch => global-modal

To do: (feel free to add to this list and/or convert items into issues as you pick them up!)

• Elements
  • Button
  • Text
  • Card
  • Overlay element
  • Layout components
    • Grid
    • Flex
    • Position?
  • Container? (for common sizing, like 100vh, or for sizing a card/overlay to varying max-widths or something?)
  • Portal element
  • Icon/SVG library => Close icon
• Styles
  • Add some global styles like box-sizing
• Behaviors
  • Focus trapping (example)
  • Scroll locking (example)

Outline the needs and goals we have for the monorepo

For example:

Goals:

• Easy configuration
• Future proof for sewing-kit migration

Needs:

• Fast build time(s)

Wants:

• Change set support (so package changes trigger a rebuild in development mode)

Add them as user stories to the WIP monorepo tool analysis sheet

Articles referenced:

Rush vs nx

June newsletter

https://docs.google.com/document/d/1bKNWegT3dsfng-2no_mPC6pQTF34xgEpqRNzA8sT2Jo/edit

Define naming convention for smaller spacing increments

What naming convention should we use for smaller spacing increments?

Full word:

• quarter
• half

Decimals:

• 0.25
• 0.5

---

Originally brought up as a discussion point in a PR:

  '0.5x': tokens.spacing[0.5],

Interested to know peoples thoughts with decimals here. I like it 🤷

Originally posted by @alex-page in Shopify/polaris#102 (comment)

Revisit "composed" component naming

A couple weeks ago we held a workshop and defined foundational component terms. These have been published to a glossary on alpha.polaris.

We are using element and composed to describe components. Element was received pretty well but we have gotten some questions about composed.

The top terms to describe a collection of components were:

• composed
• pattern
• component

Pattern seems to resonate for more people.

Feedback from Gavin:

If there's an established convention for devs, go w/ that and move on. No system gets this right.

Monorepo architecture

The repo is currently in scrappy-mode right now, which was great for Prototype phase but we need to get the repo in ship-it mode for Build 🚀

We met with @BPScott from Web Foundations to talk briefly about the direction we're moving in with a monorepo and align on what his team has planned for sewing-kit's support for package-based projects like ours. Things are still in the works with the Standardized Library Builds project, but one takeaway was that Rollup will be their builder of choice, so we'll need to take that into consideration for our technology choices (for example, Vanilla Extract).

---

Contribute to the monorepo discussion as things progress

To research:

• nx - builder with change set support

To do:

• Shopify/polaris#73
• Shopify/polaris#39
• #81
• #82
• #83

Stakeholder review prep

Last stakeholder review…

• we shared:
  • overview of the problem
  • assumptions
  • our early opinions on shared ownership
  • early opinions about how to approach the foundation
• we asked for:
  • We want to move into prototyping. Are we solving the right problems?
  • Thoughts on audience (Argo, 3rd party, systems outside of Shopify brand etc)
  • Alignment on technology choice (React + React Native)
  • Recommendations for who we might pilot this work with
  • We will need to hire front-end developers to make this foundation

This stakeholder review…

What do we want to share with stakeholders?

• Shared our work with 5 devs from outside of our team, got feedback, really excited, may start live stream
• What are the outcomes from the folder structure we have today?
• What are we high/low confidence in for the tech choices made so far? (for example, how do we feel about Stitches?)
• How do we think we should document these new component paradigms (element vs composed)? - Week 4 is dedicated to docs right now but it be useful to start thinking about that sooner?
• What was our rationale for the decisions/choices we've made so far?

What do we want or need to get from this shareback?

• Perspective/opinion on how this will scale to different platforms / languages (mobile native, react native, etc.)
  • Should we come with a perspective/opinion/hypothesis of our own? How could this scale for mobile
• We'll need to hire designers (I believe this is already in progress so may not need to call out)

Next steps:

• Share concept car - where we want to go with this prototype
  • showcase the different levers you can pull
  • what does this look like in a local system
  • this would help us answer some open questions too
  • example: we have a modal, how would you change the size, border radius, at what point does it become a different component (sheet)

Update links to polaris.shopify.com in the vault

[Foundation Prototype][Week 1 - Structure] Unanswered questions

Add any questions that need exploring to the list!

• What would be private/public?
• Shopify/alpha.polaris.shopify.com#379
• What layers of the system are we able to provide to all of Shopify and which only cater to a subset?
• Monorepo
  • Build flow between packages
  • Releases
  • Naming (what do we call the repo, packages, applications)

Build layout components

Layout enabling components to build:

• #142
• #143
• #144
• #145
• Aspect Ratio
• ContentBlock
• Inline
• SimpleGrid
• Tiles
• Wrap
• Box (Block)
• Flex
• Grid

Message teams the naming changes to components and removal of elements/composed

• Find out where the communication has happened
• Write a message to send out informing people of the change
• Call to action for feedback
• #124

Hey hey,

We recently announced that we are going to breaking components into elements and composed groups. Through feedback and iteration we have decided to keep them under one definition. There is a huge difference between a resource list and a button however we are not confident enough right now to know the value of breaking these components into two different groups.

What this means for now:

• One name, less confusion for our users and team
• We can explore different ways to document the components (e.g. surfacing total dependencies)
• The Polaris foundations are meant to be owned and maintained by everyone. This encourages this approach.

If you have any feedback or thoughts please jump into our discussion.

Design landing page website

Ideas / exploration

Include:

• Title with intro copy
• A way to show that Polaris supports multiple experiences example
• Copy with a CTA to go to the legacy admin.polaris.shopify.com site (url tbd)
• A way for users to sign up for updates via their email
• Link to open source repo

Notes:

• easter egg... tbd - pokemon?
• Don’t want this to feel like polaris.shopify.com
• Communicate a big evolution (same but better)

Update links to polaris.shopify.com in GitHub

Over 300 results when searching with grok https://grok.shopifycloud.com/results?q=polaris%5C.shopify%5C.com

Add tooling to release packages

• update .github/CONTRIBUTING.md with release documentation
• include steps on how to use Changesets #199

Move decisions to dicsussions

Classname obfuscation makes it hard to debug in browser

Compile additional insights from Workflow Mapping Project

During our Workflow Mapping research sessions, there were a handful of topics that came up that weren’t necessarily tied to Polaris’s goals and strategy, but still felt important to discuss. @jamesbull and I will compile those into a single doc, and then ask the team to review the list for completeness and accuracy.

After the list is complete, we'll determine how we can/should communicate these findings to the larger Shopify team.

Mono repo clean up

• Move icons to packages
• Rename site folder to polaris.shopify.com or other decided on namespace

Rename repo

Build Text foundational component

Include typography related properties and some basic variants

Create default values for breakpoints

Deploy style guide mirror to legacy.polaris.shopify.com

Context on the domain name we chose Shopify/polaris#86

• Add domain to DNS record store documentation for adding a new domain
• Add another domain to our manifest.yml file make sure to run dev runtime update to update the lock file