The Lego Storage Design System is designed to allow a diverse range of users to contribute to the project.
Role of a Designer
As a designer, you will create design components (atoms and molecules) in the COMPONENTS folder of the project. Each atom or molecule must be self-contained in a folder with a unique name. All files related to the component will go in this folder. This includes .hbs, .yml, .json, readme.md, and any other items such as .js and .scss files.
The .js and .scss files serve two special purposes in the design system:
scripts.js file and the .css file.The readme.md file also serves a special purpose. It allows you to add notes about the component that will be visible in the notes tab of the panels.
When creating the content for the folder, it’s a good idea to add the .js, .scss, and readme.md files in the folder even if they are empty. These can be used as “stubs” for other designers or developers to contribute to the project.
The .hbs file, must be in the folder to hold your HTML. You don’t need to include the full HTML structure (<!doctype html>, <html>, <head>, <title>, <body>), as the design system will take care of that.
Navigation in the Design System
The creation of the left-side navigation is based on the folder structure. Folders with single names such as buttons will appear as Buttons, while folders with hyphenated words such as primary-button will appear as Primary Button.
.hbs files are used to hold HTML or Handlebars code. It’s best to keep the filenames the same as the folder to have proper navigation.
The design system will not allow folder/file names to be identical. If you create a button folder with a nested folder/file called icons and a second folder called anchors with a nested folder/file called icons, only one folder/file will appear in the navigation.
The navigation gets sorted in alphabetical order based on the folder. If you’d like to sort the navigation, you can prefix the folder name with a number and underscore. It’s best to use ##_. For example, 00_typography, 01_atoms, 03_buttons, 02_modals would give you:
Nested folders and files will appear under the parent item as an expandable menu item. Once again, in alphabetical order unless prefixed with a number. You don’t need to prefix all folders/files, just the ones you want sorted.
Folders/files that are prefixed with an underscore will not be displayed in the navigation. This is ideal when you want to build a reusable component, as it may be part of a another component, but users will not be able to see it in the navigation. For example, _preview.hbs. This is a special file that sits in the root of components which builds out the HTML of all components. It’s a structural element for the design system; We don’t want to include it as a navigable element.
SCSS files get compiled into one large .css file. The design system uses a gulp file to build out the CSS. To cascade the original style, put your code directly into the folder and reference it in the main.scss file. Your code appear lower down the .css page. Namespacing your SCSS can help with style collisions.
Role of a Content Editor
The design system allows a content editor to show the copy on a page. If they are familiar with HTML, they can place the copy in the required tags and see the layout. If they are not familiar with HTML, they can collaborate with a designer or developer to place the copy in the .hbs page.
Content editors can also use the readme.md page to write notes about the copy or anything they want to highlight about the component.
For more formal documentation that is not specific to a component, the docs folder will hold .md files. For example, this page is written as an md (markdown) page.
Role of a Developer
The design system uses Handlebars to allow dynamic reusable code. In order to use the code, create a .hbs file, write your HTML and Handlebars code, and place the data in a .config.json file in a folder with the same name. Using the JSON version of a config file gives greater flexibility to the JSON stucture. The JSON file, requires a title and context object. Fractal also allows .yaml and .js versions of the config file.
The beauty of using Handlebars when building components; you can crate a single atom or molecule and then reference it in Handlebars to reuse it. The raw code (view panel), shows where dynamic or replaceable code can be placed while building components. The HTML panel shows the generated HTML as it would appear in a browser’s devtool. The Context panel displays the data in the JSON. The Assets panel shows the content of other files located in the components’ folder. The Info panel provides information about the component. Use the Handle to reference the component to be reused.