I'm curious about how other developers approach UI documentation while building projects. In my experience, I often dive straight into coding without any proper design process, which has led to issues later on. For instance, a designer might come in expecting Figma files, and I have nothing to give them, or I might take over someone else's project, and all the design details are just stuck in the CSS without any documentation. This usually results in designers spending a lot of time figuring out what exists before they can start working, and clients aren't happy about being charged for that time. Is design documentation something most developers think about as part of their process, or do they usually treat it as an afterthought?
7 Answers
Get yourself a Figma account. It saves a lot of hassle in the long run, especially when clients start requesting designs. It might feel like an extra step, but it's worth it to prevent future headaches.
This is a common issue! I've been both the builder and the inheritor of undocumented projects. To reduce the overhead, I recommend maintaining lightweight design tokens in your code—just a simple file for colors and spacing. This way, when designers come in, they can whip up a style guide quickly, rather than spend ages figuring everything out. Also, a tool like Storybook can serve as a live UI catalog for designers to reference.
I usually just document any helpful info in the code itself and ensure everything is stripped out when minified for production. This way, the unminified version is available for review during development.
I tend not to use Figma much anymore. I prefer creating a design system on the fly—documenting fonts, colors, and components in Storybook. It keeps everything organized and reusable for future pages, which speeds up development.
Totally! Storybook is a lifesaver if you set it up from the start. I've taken over projects that had none of that, and it makes things so tough.
Honestly, most of the time I leave it in the code and assume it's good enough. You hope your code is self-documenting, organized, and easy to navigate for whoever comes next. But if a designer joins later without documentation, they shouldn't expect to see a Figma file. That said, if it takes them too long to figure everything out, then it's either over-complex code or they took on too much.
I don’t document design per se, but I do have wireframes or prototypes—currently using PenPot instead of Figma. I always make sure to document my code inline, and sometimes I'll generate documents with TypeDoc depending on the project's requirements.
Haven't tried PenPot! Does not having Figma ever create issues when you hand off to clients or other designers?
It all depends on what the client is paying for. If documentation isn’t included in the scope, then it could become a point of contention. I find that it’s useful to offer as an upsell, especially when clients need those detailed designs later on.
How do you pitch it to clients without them pushing back? I'm curious about your approach.
I love the idea of using tokens! It really does streamline things and saves so much time later.