Standardizing Frontend Practices with Storybook

aquino_macareux_co_jp
aquino_macareux_co_jp

In this article, we’ll explain how we use Storybook at Macareux Digital to standardize our frontend practices and why this was necessary. We’ll provide an overview of our Storybook setup, including its key components and how we approach adding new ones. Finally, we’ll share our plans for future improvements.

We created a repository called Frontend Starter Kit to use Storybook as a tool to build a more consistent frontend. Storybook lets us document, develop, and test UI components in isolation, which helps our team set visual and functional standards for projects. With reusable, clearly documented components, our frontend remains cohesive, making the codebase easier to maintain and scale while promoting consistent UI patterns across applications.

The Frontend Starter Kit repository serves as a foundation for our frontend development, integrating essential tools and frameworks for a seamless development workflow. It standardizes our practices to maintain consistency across projects and is built using Storybook, Vite, TypeScript, and Tailwind CSS. Now, let’s explore our Storybook page and see how it’s organized:

The content is organized into five sections:

  • Documentation: Displays our color palette and a component catalog overview (more details on this later).

  • Check: Contains a style guide for verifying styles used in Concrete CMS content blocks.

  • Components: Includes all individual components, such as Buttons, Cards, Alerts, etc

  • Editor:  Used to check styles for text, images, lists and more in Concrete CMS content blocks.

  • Pages: This is where we assemble components to build complete pages.

 

Using Storybook brings many benefits, which helped us address several challenges:

  • Improved Consistency: Previously, different developers working on separate projects would create the same component under different names. With Storybook, we now ensure consistency by reusing existing components, only creating new ones when absolutely necessary and adjusting as needed.

  • Enhanced Quality: Testing for accessibility, visual consistency, and responsiveness used to be challenging and time-consuming. Storybook simplifies this process with built-in Controls (see image below) for easy accessibility checks, visual testing, and responsive design across multiple screen sizes.

  • Better Knowledge Sharing: In the past, other teams, directors and designers had no easy way to view our components. Now, stakeholders can access our component library with a single link, making collaboration seamless.

So why is it called Starter Kit ? "Starter" is because it serves as the foundation for creating new repositories. We reuse it to set up new projects and then customize it to meet specific project requirements. It’s a “kit” because it contains all the essentials: pre-built components, an editor, page templates and a GitHub Actions file that automatically generates standard issues needed for every new project.

During the development of the Frontend Starter Kit, one of our challenges was organizing the content to be easily understandable. We initially started with just the Components section, but as the project evolved, we added Editor and Pages sections to provide more structure and clarity.

We recently added a catalog (see image below) that gives an easy overview of all components. This catalog serves as a central reference, allowing developers, designers and stakeholders to see the available components at a glance. It helps everyone understand the building blocks of the application and encourages the reuse of existing components.

This all looks good, but is it easy to maintain and add new components? Once you’re familiar with the setup, it becomes straightforward. For those used to Storybook with a framework like React, this approach may feel different at first, but it’s just a matter of getting accustomed to it. One significant advantage of this method is its compatibility with Concrete CMS, allowing us to incorporate PHP code directly into the HTML.

To create a new component, we need three files:

  • HTML file: Uses Handlebars for dynamic HTML, allowing the structure to change based on props received from Storybook.

  • JavaScript file: Customizes the component’s appearance, adapting it according to the props.

  • Storybook file: Renders the component in Storybook for easy preview and interaction.

 

Here’s an example of how our HTML and Storybook look:

HTML

<div>{{dummy}}</div>
<ul>
  {{#each dummyList}}
    <li>{{this}}</li>
   {{/each}}
</ul>

Storybook

export const [Component Name]: Story = {
  render: (args) => create[Component Name](args),
  args: {
    dummy: 'Add text you want to show in div tag',
    dummyList: ['test1','test2','test3']
  },
};

For the next steps, we plan to focus on several key areas for improvement:

  • Codebase Enhancement: Continue refining the codebase by adding new features and performing regular refactoring to maintain efficiency and keep everything up to date.

  • Visual Testing: Increase our use of Chromatic for visual testing reviews in pull requests to ensure that any changes maintain the visual integrity of components.

  • Integration with Concrete CMS: Work on the seamless integration of components with Concrete CMS, making it easier for developers to utilize and implement components in their projects.

 

Thank you for reading! We hope you found this article helpful and informative.

＜ 前へ 一覧へ戻る 次へ ＞