In my experience working with design systems, I’ve found that I have to sacrifice my portfolio to do it well. Unlike a lot of other design work where it’s relatively easy to present Dribbble-worthy interfaces and designs, I fear that systems are quite a bit trickier than that.
You could make things beautiful, but the best work that happens on a design systems team often isn’t beautiful. In fact, a lot of the best work isn’t even visible.
For example, most days I’m pairing up with folks on my team to help them understand how our system works; from the CSS architecture, to the font stack, to the UI Kit to how a component can be manipulated to solve a specific problem, to many things in between. I’m trying as best as I can to help other designers understand what would be hard to build and what would be easy, as well as when to change their designs based on technical or other design constraints.
Further, there’s a lot of hard and diligent work that goes into projects that have no visible impact on the system at all. Last week, I noticed a weird thing with our checkboxes. Our Checkbox React component would output HTML like this:
<div class="checkbox">
<label for="ch-1">
<input id="ch-1" type="checkbox" class="checkbox" />
</label>
</div>
We needed to wrap the checkbox with a <div>
for styling purposes and, from a quick glance, there’s nothing wrong with this markup. However, the <div>
and the <input>
both have a class of .checkbox
and there were confusing styles in the CSS file that styled the <div>
first and then un-did those styles to fix the <input>
itself.
The fix for this is a pretty simple one: all we need to do is make sure that the class names are specific so that we can safely refactor any confusing CSS:
<div class="checkbox-wrapper">
<label for="ch-1">
<input id="ch-1" type="checkbox" class="checkbox" />
</label>
</div>
The thing is that this work took more than a week to ship because we had to refactor a ton of checkboxes in our app to behave in the same way and make sure that they were all using the same component. These checkboxes are one of those things that are now significantly better and less confusing, but it’s difficult to make it look sexy in a portfolio. I can’t simply drop them into a big iPhone mockup and rotate it as part of a fancy portfolio post if I wanted to write about my work or show it to someone else.
Take another example: I spent an entire day making an audit of our illustrations to help our team get an understanding of how we use them in our application. I opened up Figma and took dozens of screenshots:

It’s sort of hard to take credit for this work because the heavy lifting is really moderating a discussion and helping the team plan. It’s important work! But I feel like it’s hard to show that this work is valuable and to show the effects of it in a large org. “Things are now less confusing,” isn’t exactly a great accomplishment – but it really should be. These boring, methodical changes are vital for the health of a good design system.
Also… it’s kind of weird to put “I wrote documentation” in a portfolio as much as it is to say, “I paired with designers and engineers for three years.” It’s certainly less satisfying than a big, glossy JPEG of a cool interface you designed. And I’m not sure if this is the same everywhere, but only about 10% of the work I do is visual and worthy of showing off.
My point is that building new components like this RadioCard
I designed a while back is extraordinarily rare and accounts for a tiny amount of the useful work that I do:
See the Pen
Gusto App – RadioCard Prototype by Robin Rendle (@robinrendle)
on CodePen.
I’d love to see how you’re dealing with this problem though. How do you show off your front-end and design systems work? How do you make it visible and valuable in your organization? Let me know in the comments!
A little off-topic, but why not just have div.checkbox and input.checkbox selectors in your style sheets to select the right ones, without having to change your HTML? Especially since you had to go back and update the CSS anyway.
Good point. Perhaps the other method is more bulletproof for a system?
Because you increase specificity: 1 class is easy to override, a tag plus a class is harder.
And if for some reason one day you turn your
<div>
into a<span>
, you have something more to change.The best practices I’ve seen since years now tend to decouple HTML tags and styling, so tags are for HTML markup, structuring the document, while classes are there to apply styling.
My policy is always try to touch things the less you need to actually obtain what you want. Leave them be as much as you can.
Enjoyed post. IME, the REAL value proposition of design systems is solving problems at scale (and in large orgs this is more of a organizational challenge than a technical one). A methodical and predictable path is the way to go!
Almost all snippets on portfolio builder showcasey “bin” sites hardly resemble enterprise app dev. at all.
Video/screencast yourself taking through your process.
It takes some practice, but I’ve had genuinely good reactions to it around new projects. In fact, I make a point of NOT having a portfolio, and tailor my videos to each new project, relating it specifically to the client, and what may be a good approach for the project they’re interested in engaging me for.
Internally it can work as well. Once you get good at it they don’t take long to do, and you can explain in a short video the reasons why you approached things the way you did, and redo them if anything significant changes.
Documentation tends not to be read/reviewed. And just showing the ‘pretty stuff’ does belittle all of the hard work you’ve rightly pointed out is really the heart of maintaining such systems and approaches.
I am currently building my portfolio. Most of my work is non-visible work: planning, coordination, communication, discussion, analysis, etc. I decided to build up these projects more like a case study. I try to reduce the text to one sentence per visual. The visual would be a diagram related to a step, or an outcome. At the end I add one or two images of the result.
The structure for a single project page would be:
1) title,
2) one or two words describing my role in the project (i.e. research, or project coordination),
3) short project description,
4) short paragraph summarising project execution, challenges, explaining my role in the project, and also crediting other parts of the team,
5) visualisations of steps (project-specific approaches, solutions to challenges), and finally
6) visible results from the project.
The entire structure is based on story-telling. I think it’s also important to recognise that some visitors may not read any text beyond project title and associated keywords (see 2), which means that the visuals (in their specific order) should be self-explanatory to a certain degree. Another implication of this approach is also that individual project pages may need slightly different layouts, as the complexity of the content requires a page layout that goes beyond a simple image gallery – going with the story-telling idea, visuals may have different sizes and are arranged in a manner that supports understanding.
As a design manager in a hiring position I would value this kind of work above a bunch of shiny JPGs to be honest.
Hi Robin
We use a change log. It will help maintaining the Code Base and also shows all changes that a commit or merge touched.
Hiii everyone
I enjoy a lot the kind of work you explained in your post. I am a Front-end developer and I create HTML and CSS layouts, I am not doing the design part, and sometimes it is very hard to make designers and programmers understand the importance of being methodical and to build things with components in mind.
My team mate and I are the persons that take the extra work of creating HTML+CSS components, to build a design system and a documentation, and to “fight” with more that 40 programmers and 3 designers, so that they create the tons of pages that the website needs with all this in mine.
I love it but it is exausting and frustrating sometimes, and I think our work it is not well valued ;)))
Thanks for the write up! I’m battling this same struggle right now.
Not sure how I’ll solve this, but I’m working on the best way to tell this story.
Guess I’ll be back to share and learn.
Enjoy this post a lot since I am thinking to add a similar DS case to my portfolio. Do you guys know any good examplew of DS case?