From Theory to Practice: harnessing Typescript for successful Atomic Design implementation

Hello, welcome to my talk, Leveraging TypeScript and Atomic Design, a Pragmatic Approach. So, this is the talk structure so I can follow through.

As an introduction, I'd like to go through common conundrums in code structure and then understanding TypeScript and Atomic Design fundamentals. I'd like to go quickly on that.

I think the most important part, really, is the real world challenges and considerations that you may not find online. And, of course, I'll show you some practical implementation examples.

So, first, common conundrums in code structure. When I first started in tech after my boot camp, I was looking at good tips on how to structure your codes in the right way, and those three words were everywhere in theory. Readability, efficiency, flexibility. And it sounds good. But when you actually start coding and building products, you realize that they can quickly become contradictory in practice.

Contractability, number one, is efficiency versus readability. The more you optimize for efficiency, the more abstract your code gets and there's a line where readability isn't good. Now, everyone knows about that. However, how do you sense when the line gets crossed? That is harder.

Flexibility versus efficiency. The more efficient you are, the more your code ends up being super consistent, which is great. However, there's a line where it's not great because then if you want to make changes, then it's problematic because everything basically crumbles. Flexibility suffers. Again, that's something which may sound, yeah, okay, that's fair but how do you sense when the line gets crossed? That is harder.

And then everything becomes at odds with each other eventually at some point, because then your code is consistent because it is efficient, but then you have to add exceptions as you go because you need some room for flexibility, and exceptions are fine until they're way too numerous to be exceptions. And then everything suffers. Efficiency, readability, flexibility, everything. So again, when do you sense that the line gets crossed?

Now, I've been told, you know, if you plan ahead, it won't be a problem. That is only true if you expect that your product will never evolve, which is unlikely. And in my opinion, the best way actually to go ahead and code a product is to not plan, is to create a separate repo and you cut something on the fly, and this is how you get to experience the nuances beforehand, because then when you do plan, you don't plan with a cold head. You plan knowing exactly all of the subtleties, because you've gone through coding it separately and you got to understand where something can be a problem eventually. So that is way better in my opinion than just planning. Just hack around, spend a weekend coding something quickly and then plan and do it properly. So yeah, here's what happens.

Start of day zero, panic, what am I even doing? And this is what I did. I thought of a product that I admired and I actively found out how that company has achieved that. And that's how I came across Atomic Design with Airbnb. My mentor actually told me, you go build on the shoulders of the giants when you're basically a startup. And this is what I did. Took inspirations from all of these companies and all of them had this thing in common and it was Atomic Design. So yeah, that's how I came across it. And again, regarding TypeScript, I was actually using JavaScript all these years and that's how I came across it as well. I was thinking of a library that I really liked using and that I wanted to scale in the same way. And it was open source, so I checked its source code and it was TypeScript. So yeah, all the UI libraries I loved were using TypeScript. That's how I knew that there was something good there. And after conducting some more research, I saw that Airbnb as well was at the time migrating to TypeScript. And their postmortem analysis showed that 38% bugs in the Airbnb codebase were preventable with TypeScript. So yeah, that's how those two things came together. And I'm happy to share years later and after building a lot of functionalities that those two together are extremely powerful and can solve most of the code conundrums that we've seen just now and made REF achievable, which is basically readability, efficiency, flexibility, and finding the right lines and nuances in between them to have something which is really robust and something where you can also collaborate with other people.

So one, again, I'll be short on that, understanding TypeScripts and atomic fundamentals. You can find a lot of things online. But let's go through that so that we are all on the same page.

So atomic design fundamentals, really, it's about making you think in a rigorous scientific way. And when you look at a page, it's a bit like, let's say that you're a music producer. When you hear a song, you don't even hear just what consumers hear. You hear all of the different layers of the music, how the sound was made, from the smallest thing. You recognize a little drum. You recognize a little pattern. You don't see the music as a whole.

And I guess for front-end developers, I guess it should be the same way, at least in atomic design philosophy. When you're looking at an app or when you're using yourself a product, it's a new way of thinking. You don't think in terms of pages, for example. You spot and you organize patterns automatically in your head and you visualize how the code should be. You notice the smallest bits first. You combine the bits into progressively larger bits until you end up with a page. You don't start with a page and work down. You basically do things like Lego.

So, again, this is an example for you to see, when I look at those two pages here, I'm noticing first the fact that, okay, there's an image and there's an mp3 player. Okay, those are the variables. This is what changes. Then all the rest is the same. I see the little tag system is exactly the same. The cards are the same. The titles are the same. So, here in my head, I can already visualize the code. There is one changing variable, the type of assets. There are little things that are put together, like the tags, the shadow on the card, the title, the little arrows, you know, all of these things, and you have also constants. All of those are always the same. The only thing that changes is this.

So, again, in your code structure, you kind of visualize how things can work. And, again, this is a question, as well, especially around forms. Forms, when I talk with fellow frontend developers, this is something that they hate. But I think that forms also can be greatly simplified by just realizing how much they have in common and how you can create form generators where it's actually really fun to build. And it simplifies things greatly because you look at it from a completely different way and you see more similarities than differences.

Again, to educate your eyes, I would invite you, as an exercise, to look at Airbnb's storybook or any other companies that you see that have a storybook and just get inspiration from what can be those little things that you may be missing when you go through Airbnb. When you see a little skeleton like this, for example, when the page is loading, you understand which file it is in their code base and what exactly it does and the different variations. This is great for you to basically go on your own and do the same.

Again, TypeScript, I'll go fast on that as well. I just wanted to make a slide on why are some developers skeptical because I just think it's important to have empathy when you work with a colleague who may still be skeptical about TypeScript to understand so that when you try to explain to them why it's good, you kind of understand their pain points. Visually, simple codes can look complicated. Libraries usage can throw unknowing type or package version mismatch errors. It can feel like an overkill. TypeScript code bases can appear cryptic. Initially, it can make you feel like productivity is slowed and you suddenly feel like you have to think in TypeScript, and coming from JavaScript, it's very weird. Is this you or a colleague? Again, they are really important points. Is your refactoring intelligent, which makes it faster, basically, to write because you have suggestions. Is your on-boarding for people, basically, your code is documented, and if you write something which would not be compatible with the code base, it would break or it would tell you straight away you can't try to pass that. And there are objectively less bugs, again, remember what we said about the Airbnb analysis. But specifically relevant to atomic design, it's the same way of thinking. It's very compatible. When you create your types, you basically are looking at similarities between things to be passed through. And types are also the best form of documentation. Just like you have storybook for the visuals. In our opinion, TypeScript is basically the storybook of your code base. It's basically a documentation. The function signature is a theorem and the function body is the proof. And again, types define the way that UI components relate to each other. So that's how you have to look at your types when you're creating them and what is needed for everything to work as a unified system. So you should be able to visualize the components and hierarchies as you read your types.

And again, that may sound obvious. But again, I think you cannot underestimate how far you can push that. Understand how far types can make you go. And for that, I think you can take a lot of inspiration in open source code bases out there of the tools that you really respect, and that you're using all the time.

It definitely helped me when I got started my startup to understand what kind of types I could pass through, and how... You know how some people are still skeptical of TypeScript because they say it makes them think in TypeScript. That can be literally a superpower, because it does make you think differently.

And when you look at open source code base written in TypeScript, it really does give you inspirations for all the doors that it can open, for what you can do. Here, for example, this is an Andy input number file. You can see everything that they pass through. So yeah, you can create basically your own UI library in your code base, where you can pass the size, a lot of the things that your product may want to have, and pass enums, or something like that. So again, take inspirations and really push you and leverage the types in the way that you would not be able to do just with JavaScript, either because it's not how it would make you think, either it's because it would mean that it's too risky, because you're not sure what to pass. Or other people might not know what to pass. Or you will need to document everything. And so it's just easier in JavaScript to create duplicate files.

So yeah, just try to leverage the types and go and fish for inspiration in really good, open-source code bases to see the power of it.

Now, the really important thing here are the real-world challenges and considerations. Problems, or potential problems, that I'm sure you will recognize, that I think are exacerbated by using TypeScript with atomic design. So it's just a word of caution, something that you have to be careful when you code.

There is a very delicate zone between over-engineering too early, and it complicates things going forward. And writing codes that work for now will later cause a huge mess. Now, this is easy to spot. You know, as a programmer, you know when you're coding something on the fly and you're telling yourself, either I'm busy to do it now, I'll do it later, or not now, I'll do it later, or this is just temporary. You know when you're doing something that just works for now. Like, for example, you type any everywhere. Okay, works for now, any, whatever. Okay, you know that.

This is way more difficult to spot. Because again, you know this saying which says, the road to hell is paved with good intentions. There is also a road to horrible code base, which is also paved by good intentions. You may have a really good plan and you execute it and you don't realize that, actually, this is not going well. It is difficult to spot because usually you spot it later. You go back to your code and you realize how complicated that is. Or someone else has to collaborate with you and you're like, what is this? So usually you spot it after you've coded rather than before.

So, yeah, a sign that you may want to take a break and think through it again is naming. This is a big overengineering red flag. If you struggle to find the right names for types and variables, then yeah, there is something there. Normally, it's like when they say that if you can explain something, it means that you've understood it. If you can't name something, it means that there is something in your logic that you're missing or that you may not completely fully understand even if it feels like you do. It's the same thing. Names are basically, you explain what it is and if you can't name it, you can't explain. It's a red flag. Chances are either you think you know how it all works, but you actually do not, again. Or you may be trying to fit in too many different purposes in there. Welcome to the chair.

So the chair is a good example of something where... I give you an example, okay? Like you're writing an index file where you have all of your different buttons that you can have and someone passed a theme and different props, and it will generate the right button. Okay, cool. Now, it's a problem when your buttons become so different in the UI and in the different things that you can take that you should probably create a separate file.

You should create different buttons file and have an index file which imports and exports them all. And then you basically reference the file directly with the right required props. Because if you have, for example, only one file which has all of the buttons in it, and then it takes a theme and a lot of optional properties. If you have too many optional properties, it doesn't document your code anyway. Because it's like, what am I supposed to pass? I can pass 1000 things, which is required, and which would break if I'm not passing it. So again, really try when you're writing your types in TypeScript to understand the limits. When you're adding optional properties and optional properties, at some point you have to stop and you have to create a separate file, sorry, a separate type. When one of those optional properties would create a problem if they were not passed under a certain condition of another thing inside of the tab.

So yeah, welcome to the chair. Do not do not do that. So yeah, again, take a break. You know, because then you abstract too many things and then you end up with code depth. And again, it can be easy to write something new, but maintenance can be hell. So just don't pat yourself on the back because you've coded something which works, which is a new functionality, really, really understand that you need to take breaks. And again, not only this is more difficult to spot the over-engineering too early, it's also way more difficult to resolve. You can refactor this. You can refactor something that you've made where you're repeating yourself, you haven't typed any and whatever. Okay, you can create a type afterwards, understanding what it was. You can refactor, but for this, you completely have to reset. And there's more sunk cost fallacy, which means a lot of people don't reset. They just try to adjust and adjust and adjust because they spend so much like engineering plan on this, not even time, but just efforts in making it work that they don't reset when they should. It is easier to refactor, duplicate code that's been copied and pasted around. It is easier to refactor verbose code or types that can emerge and you should refactor it. It is harder to maintain something short that's harder to decipher and understand because they have a lot of ramifications that you do not see because you only see two lines, but you don't see the consequences around that. And it is harder to rewrite something that impacts again, many different parts of the code base. So I'll give you like a short example of things that sometimes when I was in the flow, I would have wanted to refactor or abstract even more.

So this is an example, okay. In that app, you have feeds of like sculptures, paintings, classical music, et cetera. These are all like what the app revolves around. And here I have basically a generator of the cards, which tells me, okay, depending on the category past, I will show different things.

And here I could have not repeated myself. I could have said instead of looking through, like having the type of category being the most important one here, and repeating images, I could have just had, you know, iCard type which takes, you know, what it passes as an asset. You could take an image or you could take an MP3. And then this would not repeat itself. We'll just have case, image, show image, case, music, show music.

No, I went with this repetition and that was honestly my saving grace because you want to stay close to product. You want to avoid building up product driven exceptions over time. For example, each category can do whatever they were able to show. You can create nuances around that and they can be added without having to make a lot of adjustments. I'll give you an example. Maybe you have a sculpture and a painting which show images. However, the painting may show something on top of it. And then your switch case doesn't work anymore because it's depending on the category. It's not depending on the image shown.

So yeah, you don't want to alienate the codebase from where it's actually building with unnecessary abstractions. Your UI types should document the product's codebase. And it should help visualizing the products as you go through the code. So yeah, stay close to products. Make sure that your domain language is close to products. And if you're abstracting too much, you will see it because you will not be able to visualize what you're actually building when you're reading the code. So yeah, again, if you need excessive comments for what your types are supposed to do and help with, that's a red flag as well. In UI-UX, your types should serve as the documentation itself and be the source of clarification. And if you need to comment too much on top of it, it means that they were not doing the work that they were supposed to do. It's not clarifying on their own. Again, practical implementation examples, because that's important for you to kind of understand how that translates into real code bases. I have in my code those folders.

You can call it however else you want, but those names are super good because they were scientific, they were objective. And anyone else on the team, when they understand the definition of each are aligned and they will not change over time.

So atoms, smallest bits extremely usable. 90% of the styling happens there. Molecules, I send a little group of atoms with minimal styling, mostly to make them fit well together. Organisms is what I call the UI, UX logic layer. There's no styling. It's components decided the correct generation of UI of molecules and functionality based on the data that it receives. The page are only there to pass down data. It gets the right data and pass it down. And templates usually encapsulate a page, at least for me, and transcends the page or it would be the main layouts.

So yeah, a good example of atoms would be, for example here, the icons file where you won't need, if you need to change an icon one day, it's just all in one place. You pass all of the props that you want, like the size, the color, et cetera. And then people working with you on a code base know exactly what the different icons are available and they don't need to look for it. Again, like paragraphs, things like typography. Molecules, a good example is the form making sure that when you have a form, they can show in different UIs. So again, you can have a form which is in a row, in a column. You can have some forms which have an image, some which don't. That would be, for example, a good things for a molecule and also the spacing, like the row gaps, for example, the column gaps, all of that stuff. Gluing the atoms together.

Organisms basically creates the molecules and make sure that given the data that it's past, it's showing the right thing. So for example, here, if I want to show a radio element, then I will call the molecule which takes care of gluing together the radio elements. Same for checkbox, ratings, et cetera. It creates the cards, et cetera. So yeah, the organism is the kind of machine. And yeah, templates, transitions, for example, good example. You know, when you fade a page, when you scroll to the top, those things encapsulate the page, but also menus which stay between pages, et cetera, and devices.

So yeah, forms I think are super important because it simplifies greatly to use TypeScript for the forms. Forms scare a lot of people, but they can be greatly simplified and reusable. And I think if you have a look at this type of code, for example, it can give you inspirations to how you can make your forms basically very hands-free and very simple at the same time.

Yep, and again, make sure that your types really document everything that's needed to work as a unified system and that you can visualize your product when you're reading through the code without any comments or omitting needed.

Yep, again, this is for you so that you can have a look later. So yeah, as a conclusion, Atomic Design ensures that everyone, users and teams, is all on the same page visually, intuitively and in the mindset and TypeScript ensures that engineers are all on the same page to an even deeper level. Everything needs to be clearly defined and expected. Remember the words of caution and you'll be fine.

To those who want to adopt existing code base to Atomic Design, I would say that a really good way to do it is to implement storybook as you go. So yeah, check storybook online and try to adopt it and you'll see that it's going to make you think in those terms.

Some readings again, Brad Frost, anything from Brad Frost is great to read. He's basically the father of Atomic Design and he's been writing a lot about it. Thank you so much for attending my talk. Again, check Custodian Careers over time. We love ambitious learners and don't hesitate to contact me and to ask me any questions.