VTEX Styleguide

Plug-and-play

Styleguide makes us work faster through basic challenges so we can tackle higher-order ones. Although every tool has a learning curve, we provide opinionated components with smart defaults so devs can get started as fast as possible. Making opinionated components does takes more time than non-opiniated ones, but this investment in time pays off in the long run. Customization should be a possibility, not a requirement.

Empowering

With teams moving in lightning-speed and with full autonomy you don't always have the resources to focus on crafting the best experience. With Styleguide all teams are empowered to offer a baseline-level experience even if you don't have a dedicated Designer or a seasoned Front-end developer.

Consistent

Being consistent has an impact much beyond brand presence and a better sense of quality. Reusing interaction and visual patterns makes for a more fluid experience using VTEX products, and this arguably improves user experience. A Design System is the main tool for promoting alignment and improving consistency in whatever it touches.

Reusable

The impact of the work you put in a Styleguide component is multiplied by the number of projects are reusing it — and this number grows every day! From a company-level a culture of reusability reduces code redundancy and increases overall quality with well-tested, bullet-proof solutions.

"A shared language is fundamental to collaboration, and that’s exactly what an effective design system provides. It gives people the tools and processes to create things together. They can build on one another’s work, rather than recreate the same things from scratch."
Alla Kholmatova, Design Systems (Smashing Magazine)

Two worlds, one system

Styleguide today fuels two distinct worlds with one shared system: Admins and Storefront. Each of them serves very different users, with different contexts and needs, which implies in their own guidelines and principles. While lots of atomic components are easily shared between these worlds, others were designed with those principles in mind and would even feel weird elsewhere — which is good!

In the future we expect each system will have their own website with their own guidelines.

Admins (B2B)

VTEX Admins are the administration panels where merchants manage everything about their ecommerce. Although not all Admin users are highly-technical, they do receive some training and end up being highly-skilled just because they use it in a daily basis.

Storefront (B2C)

This is the actual ecommerce, the website where people buy stuff. For most of VTEX history we didn't get into this, but with the new CMS system we're starting to provide out-of-the-box Store Components that clients can customize with their own visual identities.

The team

“No hay banda, il n’est pas d’orchestra, it is all an illusion.”

Since the beginning we recognized that due to teams sizes in VTEX and the large amount of work everybody had in their own teams we would need to be all together in this. The Styleguide was born from deep inside the product teams, with developers and designers at the same time working in the products and building the system.

Until today this pattern remains, and all our processes and rituals are deeply collaborative. We try to implement the horizontality of VTEX, fostering each team's autonomy and freedom, and challenging us to constantly seek alignment and sharing knowledge as a way of tapping into the collective intelligence.

Our rituals

Want to discuss some ideas or work on them along with other people? Everyone is welcome in our weekly rituals, just show up!

Morning Working Sessions: bring your questions, or find something to help others (our Github Issues are a great start).
Alignment Meetings: just put anything you want to discuss in our shared agenda, or just come and discuss with us.

If you're inside VTEX check our Slack channel for the updated location and times of these meetings.

How to contribute

There are no rules or regulations for how a Styleguide contribution process should work, but variations on the model below tend to work super well. You can use this process either if you would like to request a new feature or report a bug.

1. Create a Github Issue

Documenting your demand is the first step. We designed some Issues Templates on GitHub to help you frame your need with all necessary context for others to consider it, compare with existing solutions or start researching for solutions. Help us help you!

2. A designer to the rescue

Either if you're a designer or not, collaboration with others is crucial at this step to make sure the proposal makes sense in the broaders sense of VTEX products. At this point we might find that your need resonates with others projects, or that it's already contemplated by existing solutions.

3. Developers hop in

With some research done we will have a clear picture if we need a new component, or just a variation on an existing one. With the specs done, some Devs might come help you with the implementation, making sure all VTEX development guidelines are followed. If not, feel free to step up anyway, leveraging the knowledge you find in documentations like this one you're reading.

4. Open a PR

If the specs were well-though and you followed all written rules for development that you could find, this step should be quite straightforward, with no surprises. Still, there can always be some console.log you left behind or design tip someone might have to share with you, so come with your heart open. With just 1 approval you're already good to go.

Introduction

VTEX Styleguide is our Design System, the home for all our reusable patterns, components and assets related to product design in VTEX. It's a common language of tools and processes to facilitate how we collaborate and share knowledge across teams and projects.