In this dialogue, two speakers compare monolithic and composable approaches to Design.md files, focusing on how to support multi‑theme (light/dark) scenarios when the DesignMD specification currently lacks explicit guidance. They discuss the trade‑offs of maintaining a single large Design.md file versus breaking it into smaller, composable pieces, and how to manage technical debt during the transition—whether to adopt a lazy, on‑demand "agentic" design system or to proactively refactor. The conversation also covers their current divergence from the spec, plans to realign as the spec matures, and practical experiences using DesignMD with Claude Design, Figma Make, and Claude Code, noting that while the integration works well (about 70% coverage), occasional gaps remain. They mention intentions to benchmark the large file approach to determine the optimal strategy.
Chapters
How do you view a monolithic design.md versus a composable approach? How do you tackle the debt in transformation? Do you approach building an agentic design system lazily as it comes up or actively? I can start, Billy. I think you and I probably are thinking the same along the first question, monolithic versus composable. In one instance, you've got multi-theme and then within themes, you've got a light and dark mode. Design MD doesn't yet— the spec itself does not define and give instruction for how to support that scenario. And so if your design system is supporting multiple products with different themes and, and it's fairly complicated, then what we're using for now is a single theme would have a single design MD file representing it. And then we've actually diverged a little bit from the DesignMD spec when it comes to light and dark mode into our own solutions. Given the spec is so young and it's evolving quickly, but its momentum continues to build. We're very conscious when we diverge from the spec, but we, we're also very confident that it's going to become a key ingredient in the future for most design systems. We're okay diverging from that, knowing we're going to have to go back at some point and bring it in line with the spec. As the spec matures.
Right now we have, for one of the themes that we're working on, we have a massive— I mean, all the components are defined in there following that. And that's always a conversation that we're having. Does this make sense to have all those definitions in there? Is this too much context to go through? Um, and we want to we plan on taking a look and maybe running some benchmarking to see what's the best approach for that. Cause it does seem like a lot in a single file, but also so far we haven't had any issues. I saw someone asked if we use DesignMD and Claude Design and yeah, we've used it in Claude Design. We've used it in Figma Make and just Claude Code. And we haven't had any issues getting any like bad output from those. I would say it's always probably 70% of the way there. So it always misses something, but it's, it's a lot better than without.
