Quick Starting Guide

This quick guide will help you understand the basics of Backlight.dev to let your start your Design System.

Understanding the Basics

If you're familiar with the fundamentals of what a Design System is, skip to the next section .

A Design System is a central place where every element of your design is referenced to help you keeping your UI/UX consistent. With Backlight.dev, all the components of your Design Systems live together along with the code that powers them.

Global Interface

In your Design Systems live different types of components:

  • Design Tokens: they're minimal components in your overall system, serving as a storage place for global references like colors, spacing, fonts and typography, etc. From a developer perspective, you can see them as global variables used in compoonents composition.
  • Components: here are your raw components, in their default version matching your design systems behaviors, with their variations. Thinks them as primary-button, secondary-button, card, badge etc.
  • Templates, Foundation, etc (optional): they're advanced components resulting from the composition of styled components and design tokens, like a navbar, a hero, etc.
  • Infrastructure (optional): this section contains the internal tools of your Design System, like dockit (a rendering system for built-in documentation) and doc-layout config files.

Customizable Sections

Those sections above aren't burned into the Backlight.dev editor. Their names and organization are pure convention that may be followed or not by the Design System maintainer. They're configured in the studio.config.json @packages.menu file in the ROOT FILES menu.

In your Desing Systems, every component, from design tokens to templates should be considered as functional component: they expose their properties (actions, styles, variants, etc), have their internals (states, etc), don't affect their environment and aren't affected by external components neither. From a developer perspective, you can see them as Web Components [1] .

Creating a Design System from a Starter-Kit

The section will guide you to the process of creating a Design System from one of our existing starter-kit:

  1. From the Starter Kit picker, choose one of your preference in the list, depending on your framework preference.

Congrats 🎉 ! You've just created your very first Design System in Backlight.dev! Let's spice it up!

Pick your own

We build different flavors of Starter Kits and Code Samples to help you in your Design System journey, based on existing trends in frontend frameworks. In the following screenshots, we picked the Furious Starter Kit (based on Fast for Web Components), but you're free to choose any of your preference.

  1. In your Editor Interface, select the Design Token colors. This component contains and exports the tokens regarding the colors that will be available in your Design System.

  2. In Backlight.dev, all components wrap different types of files:

    • src/ : the source code of your component
    • stories/ : the stories allow you to preview your component
    • test/ : the component's unit tests
    • doc/ : the documentation related to the component
    • design/ : the design material for this component

    Go to your Color tokens, and select the src/ folder in the pills navbar. You'll see the current tokens definitions, depending on the starter kit you picked.

  3. In the currently selected file (here: color-tokens.ts) file, edit your base tokens. E.g.:

    const accentColorValue = '#00ff00';
    const neutralColorValue = '#ff00ff';
    

    Save your file using Ctrl/Cmd + S. Your Design Systems colors preview updates immediately to reflect your changes.

  4. In the sidebar, select a styled component, like a button. The Stories had been updated with your new colors.

🚀 Now you've got your very own Design System! Try to edit the different design tokens already available, like colors, typopgraphy, space, and see how the changes are propagated to the design of the overall components.

Adding a Documentation

A valuable Design System describe precisely how to use its components, why they're designed this way, and what their behaviors are. Backlight.dev embed documentation for every components of your Design Systems allowing you to provide useful context to your users.

To so do, just create your documentation page in the doc/ tab, by adding files with an mdx extension to host your markdown doc (other extensions are also available, check the doc/ folder documentation section .

(Optional) Linking to a Github Repository

Having your work synchronised with a Git Repos Provider allow you to easily track and share changes and updates.

Let's link your new Design System to a Github [2] repository:

  1. In the Editor's sidepane, click the button to display the Source Control view.
  2. Click on the Connect button, then login to your Github account and authorized Backlight.dev to access your Github profile.
  3. In the sidepane, click the Create Repo button.
  4. In the Create Repository popup, choose the Github workspace where you want to create your new repo, rename the repo if you need, then click the Create repo & push button.

Congratulations 🎉 ! Your Design System is now synchronised with a Git repository on Github!

Use branches for your workflow

As the main branch is read-only in Backlight.dev, you do have to create a branch to edit your Design System.

To create a new branch and edit your Design System:

  1. Click the Branch button.
  2. In the Create a Branch popup, name your new branch, then click the Create Branch button.
  3. In the Editor's sidepane, click the button to go back to the Components view and edit your source files.
  4. When you're satisfied, go back to the Source Control by clicking the button in the sidepane.
  5. Check your changes, add a commit message in the section then click the Push branch-name button.

Your branch is then pushed to Github, where you can create Pull Requests from your branches, merge them, as you generally do.

Publishing on NPM

Now your Design System is ready, you can release it to NPM from the editor!

  1. In the Editor's sidepane, click the to display the Release view.
  2. Click the Release... button to build the package.
  3. In the release modal view, choose your release's type: Patch, Minor, or Major, then type a release description.
  4. Click the Release x.x.x button.

Your package is now available in the NPM registry, and will be available almost immediately in any npm CDN like UNPKG or Skypack .

Importing the Design System in MyApp

Backlight.dev goal is to provide your teammates with a ready-to-use living Design System that embed all your UI components.

You can so use it in your in-development application by using the Backlight.dev's live linking feature:

  1. In the topbar, click the Link button.
  2. Copy the displayed command by clicking the icon.

In your local dev environment, open a terminal and paste the command. You Design System will then be available as any external package, and you can import your component as any other module, like:

import { button } from @[workspace]/[your-design-system]/button

Awesome ✨ ! You're now ready to customize, document, publish, then use your own Design System in your all of your apps! Now, go through to learn all Backlight.dev features!


  1. of course, Web Components are just an example, and can use any UI framework your comfortable with, from Web Components to JS Frameworks like React, Vue.js, Svelte, or any other. ↩︎

  2. Backlight.dev also support Gitlab as a provider. ↩︎