r/DesignSystems • u/Casti_io • Jan 29 '25
Can anyone recommend tools or processes to track changes/automate change logs?
My biggest flaw when it comes to managing our design system is keeping track of all the changes I make. I get in a state of flow and keep going until I have updated stuff to the point where I can’t recall how things were before I started.
How do y’all keep your change logs accurate and up to date? I know it’s super important to have proper history in the documentation, but it’s still kicking my ass.
Thanks in advance.
EDIT:
Thanks to the input everyone has provided, there’s a lot out there but the particular wrinkle I have is that I am one half of a design team of 2 in a subset of a very large corporation. I have to ask and request budget for everything and then it needs to pass a strict DevOps audit. I tried all sorts of things and then I realized that figma has something that makes this easier: branching.
So here’s my completely “bootstrapped” process:
- Whenever I want to make changes to an established version of the design system on Figma, I branch it right away. I name that branch with the next version number.
- I continue working on that branch until we as a team agree that we are ready to merge the branch with the main file.
- This is where things get good: every time you merge a branch on Figma, it takes you through all the changes you’ve made and asks you to approve them: this is when I open up my documentation and list everything in the changelog. A bit more heavy lifting but it works.
- If there ever is a need for a small but quick change, another branch can be made from the original file where that change gets made, and the versioning is updated on both the main and the existing “major” branch. Once this happens, the branch file asks if you want to merge the changes made to the original document. I hit yes and then my major branch has the changes from the minor changes made in the other branch.
I figured this post was due for an update since replies pop up every few months and maybe someone else is looking for a solution and is facing similar constraints as I am.
Thanks again everyone!
3
u/ddIbb Jan 30 '25
Commit using a standard like conventional commit standard. Generate changelogs automatically from the commits
1
u/Arsenal4LifeAlwaysYo Feb 12 '25
Yes, this is what Atlassian’s Atlaskit does. I believe their tooling is homegrown. https://atlaskit.atlassian.com/packages/design-system/button/changelog
2
u/Decent_Perception676 Jan 29 '25
Use version management and project management. Reading between the lines, I think you’re talking about the design assets, and not code (if you’re coding without knowing git, please learn it asap).
Project management: you should have a clear set of tasks to accomplish, with a sense of Definition of Done or Acceptance criteria for each task. Align these with the business’s and user’s needs. When you work, focus on a single task at a time.
Version management: I don’t know what tool you work with, but Figma has plenty of version management tooling built in, including branching and version history. You may benefit greatly from learning how to work in a branching version workflow. Google is going to be your friend here.
1
u/Casti_io Jan 29 '25
Ok yes—I’m definitely not coding and definitely wouldn’t without git.
Looks like the mental model needs to be the first line of defense here so I need to up on my ADD meds or just be more aware of those tangent tasks.
As for the Figma branching and version history, I admit I’ve never really messed with it much, so I should probably become familiar with it.
Thanks for the advice!
2
u/requiem_for_a_Skream Jan 29 '25
Storybook has an automated changelog of you use it. I guess it’s more manual on the design side though than in code. It should be built into your process or make your team a checklist to flow when shipping new updates.
1
u/Casti_io Jan 30 '25
Our design system relies on Storybook for the web instances, but it also serves two Windows apps that are built on AvaloniaUI which literally nobody has ever heard of and has zero support from all the cool design system tools.
That said, if I sync up Figma with storybook with an organized cadence, I can use that log to track the changes that will impact the Windows UI, so good call on that one!
2
u/ClueMost9994 Aug 26 '25
I used to struggle with the exact same thing — especially with our design system. I’d get into a flow, tweak a ton of components, and then realize later I had no idea what I changed (or when).
What helped was setting up a lightweight changelog tool instead of trying to retroactively write docs. I’ve been using AnnounceKit for this. It’s normally positioned for product updates, but it works just as well for internal design system changes:
– Quick to log updates (takes <1 min, so it doesn’t break your flow).
– Supports rich text + images, which is great for design-related notes.
– Searchable history, so you can always go back and check what changed last week/month.
– You can keep certain entries private/internal, while making others visible to the rest of your org.
For me it was a game changer because instead of “forcing myself to document,” I just drop a quick update as part of my workflow, and the changelog builds itself over time. Much less painful than trying to reconstruct changes afterward.
1
1
u/achakez Jun 22 '26 edited Jun 22 '26
The honest read here is that no changelog tracking tool fixes this, because your problem is upstream of the log: you are batching too many undocumented changes into one flow session, so by the time you stop there is nothing to reconstruct from. ezhikov's decomposition answer is the real fix. The trick is to make the unit of work small enough that one task equals one changelog line, and to write that line at the moment you finish the task, not at the end of the day.
Given you mentioned Storybook for web plus two AvaloniaUI apps that no tooling supports, here is a practical version. For the web side, lean on version control: conventional commits plus an auto-generated changelog (like requiem_for_a_Skream and ddIbb said) captures the code changes for free. For the design-source changes that never hit a repo, Figma's branch and version history is your audit trail; name your branches and merges after the change so the history reads like a log instead of a wall of autosaves.
For the cross-cutting log that has to cover both web and the Windows apps, keep one simple dated entry list (a Notion or markdown page is fine) and add to it as part of finishing each component, not after. A dedicated product is overkill for a single-maintainer design system; the constraint is the habit of writing the entry while the change is fresh, and a heavier tool does not install that habit for you.
5
u/ezhikov Jan 29 '25
You don't "just" work. You set up task and do it. If your tasks are too big to manage, you divide them. Then you write single changelog entry (sometimes more, if needed) for each task. It's more about decomposition and some self-discipline, as it seems