Developer FAQ
Get up and running with generated components
How to set up your app for using Overlay ?
Overlay can generate Vue.js / React / Vanilla HTML components.
In web design integration, there are several tools :
UI Frameworks: Element, Material Design, Bootstrap, Bulma, Tailwind CSS, etc ...
Languages: CSS, SCSS, Less, Stylus, etc ...
We choose to focus on SCSS, because it's a very powerful and flexible language.
Of course, it's still possible to use Overlay with other setups, this adds a little work overhead after getting components code. In the future we will add more and more setups.
Here are the available setups:
React / SCSS Module.
Vue.js / SCSS.
Vanilla HTML / Vanilla CSS.
Add a reset style file
To avoid big and painful css files, Overlay only adds required CSS properties to your component, for example Overlay doesn't add margin: 0
to every p
tag. Browsers have default CSS properties, to avoid conflict with your design, add a reset.css file to your project's root.
Setup SCSS for Nuxt.js Project - 5 min
1. Install SCSS Webpack loaders.
You can test by changing with the lang
attribute for <style>
tag.
Pro Tip: We recommend to also use scoped
attribute, to avoid style conflicts between your components.
2. Create a stylesheet.scss (you can choose your own name) file in your assets
folder.
assets
folder.A stylesheet example :
3. Test your stylesheet.
Import the stylesheet inside a component and use one variable :
4. To avoid adding this import on all your component files, we recommend installing styles resources nuxt library : https://github.com/nuxt-community/style-resources-module.
Here an example of styleResources config :
You are now ready to import Overlay components in your project 🚀
Setup SCSS for Vue.js Project - 3 min
1. Install SCSS Webpack loaders.
You can test by changing with the lang
attribute for <style>
tag.
Pro Tip: We recommend to also use scoped
attribute, to avoid style conflicts between your components
2. Create a stylesheet.scss (you can choose your own name) file in your src
folder.
src
folder.A stylesheet example :
3. Test your stylesheet.
Import the stylesheet inside a component and use one variable :
You are now ready to import Overlay components in your project 🚀
Setup SCSS Module for a React Project - 5 min
1. Install SCSS Webpack loaders.
You can test by changing with a CSS file to SCSS by changing his extension to .scss
then change his import.
2. Change your CSS file extension to *.module.scss
(don't forget to also change the import), to enable SCSS module.
*.module.scss
(don't forget to also change the import), to enable SCSS module.A CSS Module is a CSS file in which all class names and animation names are scoped locally by default.
Test your implementation by injecting styles from your SCSS module into a component
3. Create a stylesheet.scss (you can choose your own name) file in your src
folder.
src
folder.A stylesheet example:
4. Test your stylesheet
Import the stylesheet inside a SCSS module file and use one variable :
You are now ready to import Overlay components in your project 🚀
How to take in hand Overlay components code ?
Overlay is a design to code tool. It is a new way of working for developers who have to get familiar with generated code. Your challenge is to understand how Overlay builds components.
Pro Tip: For your first components take some time to inspect the whole component with your dev-tools to understand how Overlay compiler develop components.
1. Work as a team.
Before you start, the most important thing is to coordinate with your designer. Design-to-code is not only a matter of tools, processes and workflow are key ! Make sure you agree on :
Style variable names (ex : we decided to name all variables like this >>
blue-primary
).CSS class names (ex : everything in english, business related names).
Component granularity: How to split your mockup into components.
Pro Tip: When you start with Overlay, at the beginning of your first sprints, sit 10 minutes with your designer and export components together.
2. Import the component in your project.
The first step is to copy/paste the new component in a new file's project, then import this component into your app, and display it.
3. Improve the HTML semantic.
Overlay only generates <div>, <p>, <input> or <img>
tag. You can change these tags with <h1>, <section, <header> etc..
to improve your app semantic. These changes won't affect the current style. Be careful, Overlay doesn't generate <table> or <form>
tags. In these cases, the layout/style must be changed.
4. Import your assets locally.
Overlay uploads all your component's assets on a secured server and injects them into <img>
tags. Then you can download all your component's assets from the component's page, tab "assets".
Here is a raw img
tag coming from Overlay..
.. that becomes
5. Add dynamic properties.
Overlay compiler uses padding and margin to position elements in the DOM. Sometimes, to add some dynamic behaviors, we need to use flex-grow, space-around and other dynamic properties. Don't hesitate to change the generated style according to your needs.
In some cases, we, developers, want to use relative units measure instead of pixel (%, rem, vh, etc...). Feel free to change it to adapts the measure unit to your context.
6. Add dynamic content.
Overlay uses static data for components. Don't forget to add your data if needed, using props.
That's it ! you know how to read an Overlay component, keep in mind that the more you read generated code, the more you will be comfortable doing so.
How to add a custom stylesheet path ?
If you need to import the stylesheet path in all your components, you can fill the stylesheet path in your Overlay project settings with your own path.
The import will be present on top of all your component style part :
How to reduce the number of generated style lines ?
Overlay makes automatically two optimisations on the number of generated style lines :
@The duplicate styles merge : Overlay merges classes with the exact same style (except for containers)
The last-of-type styles merge : Overlay merges classes where the last layer doesn't have any margin and all the others have the same margin.
How to code responsive components with Overlay ?
To start creating responsive components, make sure you know all the breakpoints and agreed on responsive behaviors with your team.
If you use SCSS, we recommend creating mixins to help you with media-query
1. Export in Overlay and integrate the component for one device size (desktop for example).
2. Export in Overlay the component for another size (mobile for example).
Two possible cases for a designer :
The common case: the component is very similar on another device (elements disappear, layout goes from vertical to horizontal). In this case reuse as possible the same layout that you did for the first export. Same layout also means same layers names so developers doesn't get confused.
The component is very different on another device. In this case the developer will certainly create a new component, do as well.
3. As a developer, I merge style properties by class
For example, if we have this class :
You will merge like this your class :
We don't move
display
property because it's already defined in desktop, and his value is the same in both size.We add
flex-direction
property inside the mobile media query because this property is already defined in desktop and his value isn't the same for mobile.We add
border-radius
property inside the mobile media query because this property is not defined for desktop.We add
background-color
property inside the desktop media query because this property is not defined for mobile.
4. As a developer, I avoid overrides in the first device size
The previous class already works for both desktop and mobile but on mobile size the flex-direction
value is overridden by the media query, it's dead code. To avoid this disagreement, we clean the class by moving all the properties with overrides.
Congratulation ! you are done 🎉. You are now a master for creating responsive component.
Last updated