In the June edition of Open Source Monthly, I highlighted Modos, a project, community, and company focused on software and hardware that designs digital devices with respect for users’ time, attention, and well-being. I also shared Cassidy Williams’ choice of the month: Theater.js, a JavaScript animation library with a GUI. This month, I’m excited about design systems and state machines. I’ll explain what these concepts are to those who aren’t familiar with them before explaining why I’m excited about them.

Design systems consist of reusable components with standards that guide developers on how to use those components. Organizations can use design systems to ensure users have a consistent and positive experience while using their applications.

State machines are programming architectures that change their behavior according to the input received. A real-world example of a simple state machine is a light bulb. Typically, a light bulb will have two states: on and off. Depending on the input it receives, like a user switching the light bulb on or off, the light bulb will respond to the input. Sometimes, state management in programming can get pretty complicated because developers have to write logic for various expected user behaviors.

Zag.js, this month’s open source project, is merging these seemingly unrelated concepts to make UI development easier for software engineers.

Open source project of the month: Zag.js

Logo of the open source project Zag.js

On April 27, 2022, Segun Adebayo announced the launch of Zag.js. He describes it as “a collection of framework-agnostic UI component patterns…that can be used to build design systems for React, Vue and Solid.js.” It includes commonly used components, such as an accordion, a menu, and a dialog. This project is innovative because it leverages state machines to manage the state and logic of each component. To further clarify the meaning of framework-agnostic, the components don’t rely on a framework to determine their state.

Because state management can be a headache, the Zag.js team made a state machine visualizer for each component. Although the team made it for their own benefit, I found it enlightening to learn about the different states the team accounted for. You can find the state machine visualizer for Zag.js here.

If you’re curious about Zag.js, you can watch the video below where the maintainer demonstrates its state machine logic capabilities by building out a clone of GitHub’s UI features:


This is a video entitled Handle Component State Machine Logic with Zag.js – Open Source Friday

About the maintainer

Segun, who prefers the name Sage because of his favorite anime, started his career as a freelance UI designer. He recognized that the development process took longer than he expected after he shared his designs with software engineers. He investigated why it took so long by asking his colleagues, learning to code, and building an application to strengthen his empathy and understanding for his coworkers’ experiences. After acquiring coding skills, Sage built and open sourced ChakraUI to increase the speed of frontend development.

As ChakraUI grew, Sage collaborated with more software developers and supported more frameworks, but problems arose. Sage described the conundrum to me, “We have the React team. We have the Vue team. Basically, the Vue team goes into our React project, copies the logic for a component, and tries to tweak the logic to use Vue syntax. However, if there’s a bug in React, how do we pipe that back into Vue? Do we DM each other back and forth saying, ‘We just fixed the bug in React. Can you help us fix the bug in Vue as well?’ It turned out to be a huge mess. From that process we learned, it would be really hard for us to serve more frameworks.”

Sage spent over 10 months creating a solution, and he named it Zag.js, which means a sharp change in direction and represents the change of course he took with his project.

To learn more about Sage, check out his inspiring story on the ReadME project.

How to contribute

Check out the website if you’re looking to implement Zag.js into your next project. However, if you want to contribute to this project, check out the repository and ReadME. This project may suit you if you’re interested in one of the following topics:

  • Finite state machines
  • Vue
  • React
  • Solid.js
  • Accessibility
  • UI/UX

If you have any questions about contributing to Zag.js, the Zag.js discord community can help!

Staff pick of the month: GitHub Docs

After chatting with Ashley Bass, a Program Manager on the GitHub Education team, I learned that one of her favorite open source projects is GitHub Docs. GitHub Docs lives in this repository and powers GitHub’s official documentation at docs.github.com. Ashley particularly highlighted GitHub Docs because earlier this year, four MLH fellows spent 12 weeks contributing to the GitHub Docs. You can learn more about the work the fellows accomplished here.

How to contribute

If you’re familiar with HTML, JavaScript, TypeScript, or you just love technical writing, check out the GitHub Docs repository. Read the contributing guide to help you get started.

Thank you, Ashley, for sharing one of your favorite open source projects with us! :star:

But wait, there’s more…

If the projects mentioned in this blog aren’t for you, but you still want to contribute to an open source project, you can discover more by:

  • Joining me on GitHub’s Twitch on Fridays at 1 pm ET as maintainers show me how to use their open source projects.
  • Rewatching past conversations with maintainers on GitHub’s YouTube channel.
  • Following GitHub Community and me on Twitter to stay up to date with my Open Source Friday Twitter Spaces.
  • Following All In, a community dedicated to advancing diversity, equity, and inclusion within open source, on Twitter.

See you next month!