Darren Xu Blog

Lessons learned from building a table component in a design system


Lessons Learned from Building a Table Component in a Design System

Building a table component for a design system might sound straightforward, but as I discovered, it can quickly become a Pandora’s box of complexity. Here are the key lessons I learned during the process:

  1. Provide the Bare Minimum

When I initially built the table component, I kept getting feature requests from various teams: “Can it do this?” “What about that?” I obliged, adding feature after feature, until the component became massive and unwieldy. What I learned: start small. Provide only the essential functionality and only add features after serious consideration. This avoids bloat and keeps your component maintainable.

  1. Expose Functionality Headless

Despite designing the table with a specific approach in mind, users always found ways to implement it differently. I should have exposed functionality in a headless way—separating the behavior from the presentation—to allow users to integrate their custom designs and workflows without being tied to my visual or structural choices. This approach, such as using Vue slot props and mixins, would have empowered teams to innovate while still leveraging the core capabilities of the component.

  1. Don’t Be Afraid to Compose Small Components

It’s tempting to create one “do-it-all” table component, but this approach can quickly spiral out of control. I should have broken the table into smaller, composable components: headers, rows, cells, pagination controls, and so on. These smaller pieces are easier to understand, test, and maintain, and they can be recombined to suit different use cases.

  1. State Assumptions and Best Practices

One of the biggest challenges I faced was addressing misuse of the table component. Here are a few examples:

By clearly stating assumptions, limitations, and best practices upfront, you can guide users toward effective implementations and reduce misuse.

Final Thoughts

Building a table component taught me that simplicity, flexibility, and clear communication are crucial. By starting with a minimal feature set, exposing headless functionality, leveraging composable components, and documenting assumptions and best practices, you can create a table component that is both powerful and user-friendly—without becoming a burden to maintain.