Using the design docs as our "source of truth"

[GBKS]

As design and development move further along, it will become more important that we all refer to the same documents as the "official" design. So far we've gotten by because we're a small group and still in an early phase of the project. As I suggested in the call yesterday, how about we use the design docs that are hosted in this repo as "the last word" on what is decided on and should match the implementation?

Figma is a great design tool, but it does not serve the purpose well of a being our "source of truth". Any editor can change anything without anyone else knowing. Technically, there is a history feature, but it's pretty much useless. This makes it hard to trust the Figma file. GitHub is more complex, but has good versioning and the consensus mechanisms of pull requests, reviews, etc. Web-based design documentation is more accessible. Not everyone is comfortable navigating Figma.

So I suggest the following setup:

1. Every designer has a "workspace" page in the main Figma file
2. Figma also has "main" pages with the designs we all agreed on
3. There's also a "design documentation" page that includes all the images that are exported to this Github repo. This is necessary because the screen mock-ups in "main" cannot be exported as they are (exported images are often groupings of screens)
4. As design progresses, we regularly add things to the "main" pages, update the images for export, and then create pull requests with the text and image updates. We can each review the PRs and then merge them. A PR should require at least 1 review by another person.

This will also allow people to post issues with design change requests that can then be answered by PRs that update the documentation. Definitely some overhead to get used to, but it should help us all be better in sync and collaborate, make things more transparent, and allow us to have really good design docs for potentially interested contributors.

What do you think?

[mouxdesign]

This sounds like a good plan @GBKS. I'm also happy that you created this thread as it has a clear framework of how to work together, which alot of other open source projects would like to learn more about as well.

Really good that we will document the entire design process as well. I would like to also add in that visual version I created of the user stories which you created, and I guess we can also add in those Google docs you created with 1) The initial plan 2) User stories.

If every thing is all here on Github it will make it easy to document later in the form of a story to share with how the build process went, what steps we took and what decisions were made and why.

[stackingsaunter]

+1 for this process. I havne't contributed much on github yet so it's hard for me to imagine how this will work in practice yet, but I agree Figma is not enough and it would be nice to have everything documented in one place in spirit of open design

[GBKS]

I'd like to suggest an update to our workflow. A problem I didn't really foresee was the pollution of components. Each of us messed around with buttons and other components in our workspaces, resulting in 10+ components named "Button" that are really hard to tell apart. See the image below.

Which one is the main one we all agreed upon? Same goes for many other components where we have multiple ones that look identical and have identical names, but only one of them is our "official" one that we should rely on.

We also had a couple of instances where accidentally main components got changed, affecting all instances (changing colors, resetting icons). The Figma history feature is useless in seeing what happened. You can go back to previous versions, but it doesn't tell you what changed - you have to manually browse the design and maybe you're lucky and can spot differences.

So I think using the main Figma file also as our personal workspaces is just too messy. Here's a new proposal:

• We have a main Figma file whose only purpose is to hold the agreed upon up-to-date design
• We publish the main file on Figma community and re-publish after each update
• We do our work in duplicates of this file
• Once we have agreed upon changes, one of us brings them into the main file and recreates them there with the main file components
• Before each of these updates, we create a duplicate and give it a version name (version history can be written in the community file description)

This creates more manual work, but should make our main file much less fragile.

What do you think?

[rabbitholiness]

Makes sense. I once had a similar workflow where we'd have a staging file to drive design iterations. Then only a couple of desigbers were allowed to copy them to the master file

[mouxdesign]

Agree on everyone working in a duplicate file to avoid the main file components being changed.

[GBKS]

Clean-up of the design file is now done. I also published it to Figma community. This new file, the published version, and the previous version are easily accessible from the landing page of the design docs. I think we'll see more activity happening in those files at the start of 2023 once V1 is done and we shift focus to V2 again.