For developers

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: Styled Components, Material Design, Bootstrap, 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.

• React / Styled components

• 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.

yarn add --dev node-sass sass-loader
npm install --save-dev node-sass sass-loader

You can test by changing with the lang attribute for <style> tag.

<style lang="scss" scoped>
    ...
</style>

2. Create a stylesheet.scss (you can choose your own name) file in your assets folder.

A stylesheet example :

// stylesheet.scss
$test: red;

3. Test your stylesheet.

Import the stylesheet inside a component and use one variable :

<style lang="scss" scoped>
@import "assets/stylesheet.scss";
...
</style>

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 :

styleResources: { 
    scss: [
        'assets/stylesheet.scss',
        'assets/reset.scss', // We add the reset.scss here  
    ]
}

You are now ready to import Overlay components in your project 🚀

Setup SCSS for Vue.js Project - 3 min

1. Install SCSS Webpack loaders.

yarn add --dev node-sass sass-loader
npm install --save-dev node-sass sass-loader

You can test by changing with the lang attribute for <style> tag.

<style lang="scss" scoped>
...
</style>

2. Create a stylesheet.scss (you can choose your own name) file in your src folder.

A stylesheet example :

// stylesheet.scss
$test: red;

3. Test your stylesheet.

Import the stylesheet inside a component and use one variable :

<style lang="scss" scoped>
@import "stylesheet";
...
</style>

You are now ready to import Overlay components in your project 🚀

Setup SCSS Module for a React Project - 3 min

1. Install SCSS Webpack loaders.

yarn add --dev node-sass sass-loader
npm install --save-dev node-sass sass-loader

You can test by changing with a CSS file to SCSS by changing his extension to .scss then change his import.

// app.jsx
import './App.scss';

2. Change your CSS file extension to *.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

// app.jsx
import styles from './app.module.scss';
const App = () => {
  return (
    <div className={styles.container}>
      Hello
    </div>
  );
};

3. Create a stylesheet.scss (you can choose your own name) file in your src folder.

A stylesheet example:

// stylesheet.scss
$test: red;

4. Test your stylesheet

Import the stylesheet inside a SCSS module file and use one variable :

// app.module.scss
@import "stylesheet";

You are now ready to import Overlay components in your project 🚀

Setup styled components for a React Project - 5 min

1. Install the lib

npm install --save styled-components    

You can test by creating a first styled component

import styled from 'styled-components'

const Button = styled.button``

2. Setup your stylesheet

Create a stylesheet.js file in your project

export default {
   colors: {
      red: 'rgba(255, 0, 0, 1)'
   },
}

Then import the stylesheet in your main React App file

import styled, { ThemeProvider } from 'styled-components'
import theme from 'stylesheet.js'

render(
  <ThemeProvider theme={theme}>
    <App/>
  </ThemeProvider>
)

The ThemeProvider component injects the theme into all styled components anywhere beneath it in the component tree, via the context API. More info on styled component theming here.

3. Test your stylesheet

Now we can test it in a styled component.

import styled from 'styled-components'

const Button = styled.button`
    background: ${props => props.theme.colors.red};
`

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.

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.

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.

import styles from './button.module.scss';
const Button = () => {
  return (
      <div className={styles.button}>
        Hello World
      </div>
  );
};

becomes ...

import styles from './button.module.scss';
const Button = () => {
  return (
      <button className={styles.button}>
         Hello World
      </button>
  );
};

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..

<img
    alt="image"
    className={styles.image}
    src="https://static.overlay-tech.com/assets/test-image.png" 
/>

.. that becomes

<img
    alt="image"
    className={styles.image}
    src="https://my-site.com/assets/test-image.png" 
/>

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.

.button {
  display: flex;
  align-items: flex-start;
  background-color: $green-hover;
  border-radius: 3px;
  padding: 10px 20px;
}

becomes ...

.button {
  display: flex;
  align-items: flex-start;
  background-color: $green-hover;
  border-radius: 3px;
  padding: 1rem 2rem;
}

6. Add dynamic content.

Overlay uses static data for components. Don't forget to add your data if needed, using props.

import styles from './button.module.scss';
const Button = () => {
  return (
      <div className={styles.button}>
        Hello World
      </div>
  );
};

becomes ...

import styles from './button.module.scss';
const Button = ({label}) => {
  return (
      <div className={styles.button}>
        {label}
      </div>
  );
};

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 :

@import "src/stylesheet.scss";

.tabVue {
  background-color: $vue-green-light;
  border-radius: 3px;
  padding: 4px 8px;
  border: 1px solid $vue-green;
}

How to reduce the number of generated style lines ?

Overlay makes automatically two optimizations 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.

This one is frequently use with list item.

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

// mixins.scss
@mixin isMobile() {
  @media only screen and (max-width: 1023px) {
    @content;
  }
}

@mixin isDesktop() {
  @media only screen and (min-width: 1024px) {
    @content;
  }
}

1. Export in Overlay and integrate the component for one device size (desktop for example).

Do as usual

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 :

// Desktop style (in your desktop component)
.container {
  display: flex;
  flex-direction: row;
  background-color: blue;
}

// Mobile style (in Overlay)
.container {
  display: flex;
  flex-direction: column;
  border-radius: 6px;
}

You will merge like this your class :

// Merged style (in your project)
.container {
  display: flex;
  flex-direction: row;
  @include isDesktop {
    background-color: blue;
  }
  @include isMobile {
    flex-direction: column;
    border-radius: 6px;
  }
}

• 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.

// Cleaned and merged style (in your project)
.container {
  display: flex;
  @include isDesktop {
    background-color: blue;
    flex-direction: row; // <-- this property is not overridden anymore
  }
  @include isMobile {
    flex-direction: column;
    border-radius: 6px;
  }
}