Symbols: Quick start guide

Symbols is all-in-one framework to build UI and it comes with its beautiful studio where you can make and see all your components on canvas. It gives unique experience to developers. You can make custom screens and pages, but its coming with built-in free 1000+ UI collection library and templates to use in any kind of web app.

Overview

Symbols is framework build using JavaScript libraries:

1. Scratch — design system library
2. DOMQL — dom rendering and state manamgement
3. CSS-in-props — CSS preprocessor
4. Dompiller — DOMQL to React compiler

When using Symbols, it comes all built-in and you can also setup the CLI tool to initialize new projects or connect to the studio.

npm i @symbo.ls/cli -g

Then you can for example start a new project with this command:

smbls create your-app-name

It will create a new folder and install all nessessary dependencies. If you have project already setup in the platform, then you can fetch your project by following:

smbls fetch

Note that your-app-name should match the key that you setup in studio during onboarding. You can change that later in symbols.json file that’s been generated locally.

If you are import Symbols over CDN:

<script src="https://storage.googleapis.com/smbls/index.c5cd721f.js"></script>

Scratch

Scratch initializes your branding as Design System and generates CSS out of it. Using it, you can manage all Design System tokens (properties) including colors, icons, typography and spacing and deliver your apps responsive to any device including printing, readers and TVs.

The configuration over Design System looks like this:

const designSystem = {
  color: {
    black: '#000',
    white: '#000',
    fade: '--black 0.1' // reusing black with opacity
  },
  font: {
    SourceSans: { url: 'https://...font.woff' }
  },
  icon: {
    logo: '<svg ...>'
  },
  media: {
    mobile: '(max-width: 480px)'
  },
  typography: {
    base: 16,
    '@mobile': { 
      base: 15
    } 
  }
}

DOMQL

DOMQL handles DOM rendering, events and state management. It’s designed to have full customisation when reusing components. DOMQL is browser friendly framework and does not require any transformations or bundlers.

Syntax is using simple JavaScript objects which will be then attached to DOM using your own tree.

const App = {
  props: {
    padding: '10px 20px',
    fontWeight: '500'
  },
  H1: {
    text: 'Hello world!'
  },
  Button: {
    theme: 'primary',
    text: 'Click me!'
  }
}

To render this object you can simply run it through smbls package.

import { create } from 'smbls'

create(App)

Create function has second parameter where you can give DOMQL context of Design System, component libraries, utilities, page routing and so on.

Passing our Design System config would look like this:

import { create } from 'smbls'
import { App } from './App'
import { designSystem } from './design-system'

create(App, {
  designSystem
})

CSS-in-props

This library allows DOMQL to use Scratch configuration and preprocess CSS thats passed through the Design System. It also enables to just pass CSS properties alongside other props and HTML attributes in the same object. The example of reusing design system token would be:

import { create } from 'smbls'

const App = {
  props: { background: 'deepBlue' }
}

create(App, {
  designSystem: {
    color: {
      deepBlue: '#112233'
    }
  }
})

Components

The components library is flat object that you pass in context and DOMQL can recognise it by strings, or shortcutting the component name as a key, for example:

import { create } from 'smbls'
import { designSystem } from './design-system'

// defining components library
const components = {
  Flex: { 
    props: {
      display: 'flex'
    }
  },
  Link: {
    props: {
      tag: 'a',
      color: 'primary',
      href: null
    },
    attr: {
      href: element => element.props.href
    }
  },
  Logo: {
    extend: 'Link',
    props: {
      href: '/',
      text: 'My Project'
    }
  },
  Nav: {
    childExtend: 'Link',
    Main: { href: '/' },
    About: { href: '/about' },
  }
}

// reusing in our tree
const App = {
  extend: 'Flex',

  props: {
    position: 'absolute',
    align: 'center space-between',
    inset: '0'
  },

  Logo: {
    alignSelf: 'start'
  },

  Nav: {
    margin: '0 0 0 auto'
  }
}

create(App, {
  designSystem,
  components
})

Note that Symbols comes with built-in atoms so you don’t have to recreate them and you can see them on Atoms page. Symbols also provides 1000+ components for you to easily reuse. You can overwrite components’ default properties or start making your own custom ones.

Pages

Now we can make pages with different routing and we can simply build quick two-pager app.

import { create } from 'smbls'
import { App } from './App'
import { designSystem } from './design-system'
import { components } from './components'

const pages = {
  '/': {
    H1: { text: 'Hello!' }
  },
  '/about-us': {
    H1: { text: 'About us' }
  },
}

create(App, {
  designSystem,
  components,
  pages
})

This way you can make SPA (single page app) without forcing browser to reload entire page.

Studio

While using the platform, most of the boilerplating is already done and you should just enjoy making your app. Platform is giving you a Figma like experience while coding and also offers you to reuse components across different projects. Design System and components management can be done on the cloud without code in realtime, and it enables developers, designers, content creators, managers and others to work simultaneously.

While using platform, you can also easily share development drafts and publish on a custom domain. In Symbols, everything happens in realtime!

With platform you can do more such as:

• npm dependencies
• Frontend and backend functions
• Reusing community built packages
• monetize with publishing to marketplace

Summary

To summarize, you can see the overall result in starter-kit repository.

This was partial list of features that Symbols provide, and for the rest you can surf documentations page.