Andrei Pfeiffer logo
Back to Articles

The code etymologistPart 5: UI Components library

Software entropy
3 min read

The Code Etymologist is a multi-part series that covers typical software knowledge that deserves to be documented and shared within development teams.

  1. Preface
  2. Part 1: Project setup
  3. Part 2: Coding guidelines
  4. Part 3: Development workflows
  5. Part 4: Product requirements
  6. Part 5: UI Components library
  7. Part 6: Data structures
  8. Part 7: Technical decisions
  9. Closing thoughts

Nowadays, we don't have to rebuild reusable UI components from scratch. There are plenty of libraries and frameworks out there, both free and premium, that provide a wide range of commonly used UI components: Tailwind Plus, Radix, shadcn/ui, Headless UI, Material UI, Chakra UI, Ant Design, Bootstrap, and many more.

However, we often need to customize them, creating our own wrappers. Most of the time, we only need to customize the styles, but sometimes we also need to extend or change their behavior. Additionally, we often need to build our own project-specific components.


As a team member, new or old, we might have a few questions, especially regarding the customized and project-specific UI components:

  1. How can we discover the components library? If they are groupped together inside a single folder or extracted in a separate repository, then it's trivial to discover them.

  2. What can they do? Declaring a typed interface is useful to discover their capabilities, to prevent using invalid input, and to aid during refactorings.

  3. What do they look like and how do they behave? The behavior aspect of UI components can be covered by automated tests. However, the visual aspect can only be consumed with our own eyes.

Now, imagine looking for a UI components library that answer only the the first 2 questions. Imagine they only display the list of components and their public interface, without showing us how they look and behave. We would have to install the library and play around with the input to discover the visual output. It's tedious. To be honest, no serios library would put their potential users through this experience.

Interactivity

Since UI components are tightly coupled with the visual aspect of the project, it makes sense to document them accordingly. That's the reason why any popular UI library offers interactive documentation.

There are several open source tools that offer the possibility to document our own UI components, however I would like to highlight Storybook simply because it's feature-rich and framework agnostic.

There are plenty of real-world examples on their showcase page that you can play with. One you might be familiar with is the VSCode UI Toolkit.

  • we can browse the UI components: Button, Panels, Radio, etc;
  • we can see what they can do, for instance, Buttons can have Default or Secondary appearance, can have Autofocus, can be Disabled, or can include Icons;
  • we can see the public API, the inputs/props, and their types;
  • we can change the inputs using the auto-generated controls;
  • we can see, and edit the code that produces an actual output.

These are all built-in and out-of-the-box features. Additionally, there are plenty of addons that we can use, such as Light/Dark theming, Viewport controls, Accessibility checks, and many more.


This kind of documentation is valuable for developers and designers, as well. You can read more about isolated components driven development which I wrote about in 2021 and it's still relevant today. It's an approach to UI components implementation, useful not only for documentation purposes, but also during development and debugging.

Continue reading Part 6: Data structures


Scroll to top