This content originally appeared on Bits and Pieces - Medium and was authored by Ashan Fernando
Highly efficient development workflow and composable architecture for design systems that encourage collaboration and reuse at scale
Design systems are essential for maintaining consistent user interfaces across projects and applications. They provide reusable components — like buttons, modals, and typography — that ensure uniformity in both design and functionality.
Choosing Between Monorepo vs NPM Packages
One of the straightforward approaches is to use a Monorepo, keeping the design system code and all the applications in one place. This makes it easy to reuse the design system across other projects. However, there is a fundamental problem with this approach. If any UI elements get modified, they immediately affect the consumer project. Therefore, an approach that can version these components becomes necessary.
And one of the obvious choices here is to make a design system packaged as a monolithic library. However, it also comes with several problems:
- Lack of Version Visibility: Developers often don’t know what changes between versions since multiple components are modified. Typically, developers need to check the release notes of the design system from time to time, which rarely happens.
- Bulk Package Installation: Developers must install the entire design system version, even when they need only a few components. This could break the system and make it challenging to do incremental updates.
Building a Design System with Composable Components
To build a composable design system, we need to structure it using independent Bit components. Each component is self-contained, meaning it can be versioned and updated without impacting others unless necessary.
You can either use one of these design systems by forking (taking a copy) the required components into your scope, or create one from scratch.
Creating a Composable Design System from Scratch
1. Initialize a Bit workspace in your design system repository:
bit init --default-scope my-org.design-system
2. Create individual components (e.g., a Button component):
bit create react ui/button
3. Build and tag components:
bit tag --message "Initial version of button"
4. Export the components to Bit Cloud for sharing:
bit export
With this setup, the design system can be broken down into manageable pieces, and each project can import only the components it needs — reducing dependency bloat and simplifying updates.
Now you can decide either to use a GitHub repository to track the workspace code or create a new workspace each time, import the components you need to modify and then snap (similar to commit) the changes, and tag and export them when they are ready.
Using Git Repository
In this approach, you can set up the CI/CD pipelines (e.g. GitHub Actions) to export the components to the Bit platform once they are ready. The CI scripts handle the complexities with the component exporting workflow and updating the dependencies.
Using Bit Platform Only
If you follow this approach each time you want to modify a component, you can just run bit init my-org.design-system to initiate an empty workspace and then import the components required to modify or create new components. This approach is clean, and for any complicated tasks, you can use a Bit starter component that acts as a blueprint to create the workspace with pre-configured components and configuration. When you create or modify components, you can use the lanes, snap tag and merge-requests functionality available in the Bit platform to manage the complete lifecycle of the design system (similar to feature branch flow in Git).
Since using the “Bit Platform Only” approach is straightforward, let's look more into using the “Git repository approach” along with Bit CI scripts for a complete design system development lifecycle.
You can find a complete list of Bit CI Scripts in the following GitHub repository.
Automating Component Versioning with GitHub Actions
If you follow a manual approach to export components, there are repetitive tasks you need to follow:
The Challenge: Manual Versioning
When components are modified, developers must manually:
- Determine whether the changes require a major, minor, or patch version update (collaboration and review before defining the sem version becomes difficult)
- Run Bit CLI commands to tag and export the updated components.
- Track changes and update version details in the repository.
This manual process can be time-consuming and error-prone.
The Solution: GitHub Actions for Automated Versioning
We can automate this entire process using GitHub Actions. You only need to create or modify any components in your design systems Git repository and open a pull request. The CI will manage the rest as follows:
1. Detect modified components in the Pull Request and Create Labels in the repository, which you or your reviewer can add to the Pull Request to bump the Sem version in GitHub.
2. The CI also creates a Bit Lane where you post that link into a GitHub Pull Request comment so that you can manually preview the Design System component changes.
3. Once the GitHub Labels are added and the Pull Request is merged, these components are automatically published into Bit Platform.
4. Then, the new version details are automatically committed back to the GitHub repository.
GitHub Action Configuration
Here’s how you can set up a GitHub Action to automate component versioning:
1. GitHub Action Workflow to Build Pull Requests
name: Build Pull Request
on:
pull_request:
types:
- opened
- synchronize
permissions:
pull-requests: write
jobs:
build:
runs-on: ubuntu-latest
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
BIT_CONFIG_ACCESS_TOKEN: ${{ secrets.BIT_CONFIG_ACCESS_TOKEN }}
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Initialize Bit
uses: bit-tasks/init@v2
- name: Bit Pull Request
uses: bit-tasks/pull-request@v2
with:
version-labels: true
2. GitHub Action Workflow to Export the Components
name: Tag and Export
on:
workflow_dispatch:
push:
branches:
- main
permissions:
contents: write
pull-requests: write
issues: write
jobs:
release:
runs-on: ubuntu-latest
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
BIT_CONFIG_ACCESS_TOKEN: ${{ secrets.BIT_CONFIG_ACCESS_TOKEN }}
GIT_USER_NAME: ${{ secrets.GIT_USER_NAME }}
GIT_USER_EMAIL: ${{ secrets.GIT_USER_EMAIL }}
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Initialize Bit
uses: bit-tasks/init@v2
- name: Bit Tag and Export
uses: bit-tasks/tag-export@v2
- name: Bit Commit Bitmap
uses: bit-tasks/commit-bitmap@v1
Note: Ensure that you have configured the required GitHub action secrets.
But, how does the other teams know that new component versions are published?
Synchronizing Component Updates Across Repositories Using Webhooks
Consumer projects that rely on design system components often fall behind when updates are released. Without proper automation:
- Developers must manually fetch and integrate the latest versions.
- Some projects may continue using outdated versions, leading to inconsistencies in the UI.
Recently, Bit Platform released the Webhook integration functionality that could facilitate complete automation by notifying and synchornizing component changes across multiple repositories.
To notify us about updates, you can use the Slack notification trigger or create a custom integration to automate the synchronization of components.
Let’s look at how we can use GitHub Action integration for consumer projects to get automated updates of modified components.
Setting Up a Webhook
First, you need to create the GitHub action workflow to update your components upon changes in the new design system. The following GitHub Action listens for webhooks and triggers an update when components are modified:
name: Component Updates
on:
# Listens for an external "webhook" repository_dispatch event
repository_dispatch:
types: [webhook-event]
permissions:
contents: write
pull-requests: write
issues: write
jobs:
release:
runs-on: ubuntu-latest
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
BIT_CONFIG_ACCESS_TOKEN: ${{ secrets.BIT_CONFIG_ACCESS_TOKEN }}
GIT_USER_NAME: ${{ secrets.GIT_USER_NAME }}
GIT_USER_EMAIL: ${{ secrets.GIT_USER_EMAIL }}
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Initialize Bit
uses: bit-tasks/init@v2
- name: Update Dependencies
uses: bit-tasks/depenency-update@v1
Then, visit the Bit Platform scope for the design system and configure the trigger following the below steps.
- Go to Bit Platform Organization → Settings → Webhooks
- Click Create a new Webhook and update the action with the following information:
URL: https://api.github.com/repos/{consumer-repo}/dispatches
Templats: Custom Template
Headers:
Accept: application/vnd.github.v3+json
Authorization: token <ghp_token> // Create a personal access token with content write permission
Payload:
{
"event_type": "webhook-event",
"client_payload": {
"owner": "{{owner}}",
"componentIds": "{{componentIds}}",
"username": "{{username}}",
"userId": "{{userId}}",
"laneId": "{{laneId}}"
}
}Note: You need to match the event type defined at the top of the GitHub workflow (webhook-event) with the event type defined in the payload. This can be any string.
Final Workflow Overview
- Developers modify and update components in the design system.
- Once a Pull Request is opened, developers get a Bit lane to test the components, and the Pull Request CI job will create GitHub labels for modified components with different sem version combinations, which you can choose from.
- Once the labels are added, GitHub Actions automatically create tags, export updated components and commit back the new version details to the design systems repository.
- Webhooks notify consumer projects of the updates.
- GitHub Actions in consumer projects import and integrate the new versions.
Benefits of This Workflow
✅ No manual CLI execution
✅ Version visibility and control
✅ Synchronized updates across multiple projects
✅ Improved collaboration and reduced technical debt
Conclusion
We can create a highly efficient, automated workflow for managing and sharing design system components by combining Bit components, GitHub Actions, and Bit Platform Webhooks support.
This workflow ensures that projects stay up to date, reduces manual effort, and improves consistency across applications.
Thanks for reading! Cheers!
Learn More
- Synchronising Components Updates Between Bit and Git: Using Webhooks
- Git + Bit: Code Meets Components
- Integrating Bit with Gihub Actions, Azure DevOps, Github CI, Jenkins, and more
- The Evolution of Source Control: Svn, Git and Bit
A Modern Workflow for Design System Development and Reuse was originally published in Bits and Pieces on Medium, where people are continuing the conversation by highlighting and responding to this story.
This content originally appeared on Bits and Pieces - Medium and was authored by Ashan Fernando
Ashan Fernando | Sciencx (2025-01-30T13:59:10+00:00) A Modern Workflow for Design System Development and Reuse. Retrieved from https://www.scien.cx/2025/01/30/a-modern-workflow-for-design-system-development-and-reuse/
Please log in to upload a file.
There are no updates yet.
Click the Upload button above to add an update.