Skip to main content
Development setup

Quartz Open uses the latest web standards to deliver the best developer experience.

Overview​

Quartz Core libraries offer many options for integrating into your project. It is optimized for both local and CDN deployment.

For instance, the Quick Start example uses lazy-loaded web components deployed to the unpkg public CDN.

Integration​

Web components

Web components are supported by all modern browsers as they're part of the standard.

Universal option for any web-based project.

Web frameworks

Quartz uses Stencil.js to generate Angular, React, and Vue wrappers.

Best developer experience with a framework.

Deployment​

Quartz Core can be deployed on a CDN or bundled locally in your application:

Content Delivery Networks

Thanks to their lazy-loading capability, the core libraries reach good performance levels on CDNs.

Best for globally deployed products.

Local installation

Local installation allows you to cherry-pick only the necessary components and optimize the exported CSS and assets.

Best for performance optimization.

A note on CDNs​

Consuming components from a CDN involves the Quartz internal lazy loader. A Lightweight script watches the DOM for unregistered Quartz elements and lazy loads them for you — even if they're added dynamically.

This is the easiest way to use Quartz. While convenient, lazy loading may lead to a Flash of Undefined Custom Elements. The linked article describes some ways to alleviate it.

Open source vs. Internal​

Schneider Electric is committed to contributing back to the open-source community. Quartz Open can be highly valuable to many who can't afford the time and money it takes to build a design system. On the other hand, Schneider Electric must protect its brand and business expertise.

That's why some modules are publicly available as open-source, and others are only available to Schneider Electric's employees and partners.

Getting the open-source assets​

Open-source packages are readily available on public CDNs like unpkg and jsDelivr.

Install them from the public npmjs.com repository for local installation.

Getting the internal assets​

This content is protected.

Schneider Electric employees: please visit this website when connected to the internal network.

Set up the Core library​

With web components​

The @quartzds/core package provides Quartz web components.

Add the following code to the <head> section of all your HTML pages:

<link
  rel="stylesheet"
  href="https://your-cdn.com/@quartzds/core@next/styles/core.css"
/>

<script type="module">
  import { defineCustomElements } from 'https://your-cdn.com/@quartzds/core@next/loader'

  defineCustomElements()
</script>

See the Usage > Web components page for usage instructions.

With a framework​

The @quartzds/core-{framework} packages provide component wrappers for Angular, React and Vue frameworks. The @quartzds/core package will also be installed as it's a transitive dependency.

  1. Install the package for your framework:

    npm install @quartzds/core-angular@next

    Angular also requires importing the QuartzModule into your app's main module:

    import { QuartzModule } from '@quartzds/core-angular'

    @NgModule({
      imports: [QuartzModule],
    })
    export class AppModule {}

  2. Make the Core source files available to your app. For example, you can route the /quartzds/core path to the static files from node_modules/@quartzds/core.

  3. Apply the Core styles by adding the following code to the <head> section of your main HTML page:

    <link rel="stylesheet" href="/quartzds/core/styles/core.css" />

See the Usage > Web frameworks page for usage instructions.

Set up Tailwind utilities (optional)​

The Core library ships with the styles/core.css stylesheet, providing classes implementing the content hierarchy principles. Those classes use a vertical flex layout by default, but you certainly want more control over this.

Quartz provides the optional @quartzds/tailwind-preset Tailwind preset tailored to be the perfect companion for implementing any layout, including responsive.

Tailwind supports many integration options, from CDN to web frameworks:

  1. Install the Tailwind preset:

    npm install @quartzds/tailwind-preset@next

  2. Follow Tailwind's installation instructions to set it up in your project.

    Use only the utilities layer in your main CSS file:

    @tailwind utilities;

    /* Add your custom styles here */

  3. Apply the @quartzds/tailwind-preset to your Tailwind configuration:

    /** @type {import('tailwindcss').Config} */
    module.exports = {
      content: [...],
      presets: [
        require('@quartzds/tailwind-preset')
      ],
    }

See Tailwind's Preset documentation for detailed instructions.

Use your brand​

Quartz supports multiple brands from the ground up. Each brand provides at least the following mandatory assets:

  • Light and Dark theme styles
  • Desktop and Mobile platform styles
  • Core icons

Look at the Brand setup page to catch your brand and see the detailed list of assets it provides.

Set up themes​

Quartz supports theming. You need at least one theme installed for your application, but you can install more.

All themes are scoped to classes using the qds-theme-{name} convention, where {name} is a lowercase, hyphen-delimited value representing the name of the theme. The included light and dark themes use qds-theme-light and qds-theme-dark, respectively.

See the Usage > Themes instructions for additional strategies for managing themes.

Single theme​

Add the following code to the <head> section of all your HTML pages:

<link
  rel="stylesheet"
  href="https://your-cdn.com/@quartzds/{brand}-tokens-core@next/dist/theme/{name}.css"
  onload="document.documentElement.classList.add('qds-theme-{name}');"
/>

Where:

  • {brand} is the package name of your brand
  • {name} is the name of the theme you want to use

Light and Dark themes (automatic)​

The following instructions automatically apply the light or dark theme based on the user's preferences.

Add the following code to the <head> section of all your HTML pages:

<link
  rel="stylesheet"
  media="(prefers-color-scheme:light)"
  href="https://your-cdn.com/@quartzds/{brand}-tokens-core@next/dist/theme/light.css"
  onload="document.documentElement.classList.add('qds-theme-light');"
/>
<link
  rel="stylesheet"
  media="(prefers-color-scheme:dark)"
  href="https://your-cdn.com/@quartzds/{brand}-tokens-core@next/dist/theme/dark.css"
  onload="document.documentElement.classList.add('qds-theme-dark');"
/>

Where:

  • {brand} is the package name of your brand
  • {name} is the name of the theme you want to use

Set up platforms​

Quartz supports multiple platforms. You need at least one platform installed for your application, but you can install more.

All platforms are scoped to classes using the qds-platform-{name} convention, where {name} is a lowercase, hyphen-delimited value representing the name of the platform. The included desktop and mobile platforms use qds-plaform-desktop and qds-platform-mobile, respectively.

See the Usage > Platforms instructions for additional strategies for managing platforms.

Single platform​

Add the following code to the <head> section of all your HTML pages:

<link
  rel="stylesheet"
  href="https://your-cdn.com/@quartzds/{brand}-tokens-core@next/dist/platform/{name}.css"
  onload="document.documentElement.classList.add('qds-platform-{name}');"
/>

Where:

  • {brand} is the package name of your brand
  • {name} is the name of the platform you want to use

Desktop and Mobile platforms (automatic)​

Set up icon libraries​

Quartz supports multiple icon libraries. All components displaying icons also have an icon-library property to specify which library to use.

Required icon libraries​

Quartz Core requires you to register at least the following two libraries:

  • the core library, containing the icons used inside the essential components (for example, the down arrow of a drop-down). The Core library embeds core icons from the generic brand as a fallback.
  • the default library, used by the components when only the icon name is specified.

Registering an icon library​

Add the following code to the <head> section of all your HTML pages:

<script type="module">
  import { registerIconLibrary } from 'https://your-cdn.com/@quartzds/core@next'

  registerIconLibrary('{library}', {
    resolver: (name) =>
      `https://your-cdn.com/@quartzds/{brand}-icons-{library}@next/dist/${name}.svg`,
  })
</script>

Where:

  • {brand} is the package name of your brand.
  • {library} is the name of the library to register.

Additional icon libraries​

Register any number of custom libraries using the registerIconLibrary() function described above.

Use the icon-library parameter of the Core components to specify which library to use:

<qds-button text="Like" icon-library="social" icon-name="like"></qds-button>
<qds-button
  text="Drive a F1"
  icon-library="vehicles"
  icon-name="racing-f1"
></qds-button>

Example (generic brand)​

Add the following code to the <head> section of all your HTML pages:

<script type="module">
  import { registerIconLibrary } from 'https://unpkg.com/@quartzds/core@next'

  registerIconLibrary('core', {
    resolver: function (name) {
      return `https://unpkg.com/@quartzds/generic-icons-core@next/dist/${name}.svg`
    },
  })
  registerIconLibrary('default', {
    resolver: function (name) {
      return `https://unpkg.com/@quartzds/generic-icons-default@next/dist/${name}.svg`
    },
  })
</script>

Set up additional brand assets​

Each brand may require additional setup for the specific assets it provides.

Now is the time to follow your brand's additional setup instructions provided on its setup page.

Set up additional facets (optional)​

Facets, including Domain foundations, all build on top of the Core library. In most cases, you just need to install the components from the facet.

Some facets may also need extra setup: check their specific installation instructions.

Full setup example​

The following example combines all the previous setup steps using the generic brand and web components.

CDN​

<html>
  <head>
    <link
      rel="stylesheet"
      media="(prefers-color-scheme:light)"
      href="https://unpkg.com/@quartzds/generic-tokens-core@next/dist/theme/light.css"
      onload="document.documentElement.classList.add('qds-theme-light');"
    />
    <link
      rel="stylesheet"
      media="(prefers-color-scheme:dark)"
      href="https://unpkg.com/@quartzds/generic-tokens-core@next/dist/theme/dark.css"
      onload="document.documentElement.classList.add('qds-theme-dark');"
    />
    <link
      rel="stylesheet"
      href="https://unpkg.com/@quartzds/generic-tokens-core@next/dist/platform/desktop.css"
      onload="document.documentElement.classList.add('qds-platform-desktop');"
    />
    <link
      rel="stylesheet"
      href="https://unpkg.com/@quartzds/core@next/styles/core.css"
    />

    <script type="module">
      import { defineCustomElements } from 'https://unpkg.com/@quartzds/core@next/loader'
      import { registerIconLibrary } from 'https://unpkg.com/@quartzds/core@next'

      defineCustomElements()

      registerIconLibrary('core', {
        resolver: function (name) {
          return `https://unpkg.com/@quartzds/generic-icons-core@next/dist/${name}.svg`
        },
      })
      registerIconLibrary('default', {
        resolver: function (name) {
          return `https://unpkg.com/@quartzds/generic-icons-default@next/dist/${name}.svg`
        },
      })
    </script>
  </head>
  <body class="qds-main">
    <div class="qds-main-section">
      <qds-title layer="main" level="section" icon-name="rocket">
        Get started with <strong>Quartz Open</strong>!
      </qds-title>
      <div class="qds-main-subsection qds-related">
        <qds-title layer="main" level="subsection" icon-name="clock">
          5-minutes tour
        </qds-title>
        <p>
          Discover all the greatness behind the components and styles of Quartz
          Open by following the 5-minutes tour!
        </p>
        <qds-button
          importance="emphasized"
          text="Take the tour"
          icon-name="rocket"
        ></qds-button>
      </div>
    </div>
  </body>
</html>

Local installation​

  1. Install the packages:

    npm install @quartzds/core@next
    npm install @quartzds/generic-tokens-core@next
    npm install @quartzds/generic-icons-core@next
    npm install @quartzds/generic-icons-default@next

  2. Make the assets available to your app.

    For example, you can route:

    • /quartzds/core to node_modules/@quartzds/core
    • /quartzds/tokens/core to node_modules/@quartzds/generic-tokens-core
    • /quartzds/icons/core to node_modules/@quartzds/generic-icons-core
    • /quartzds/icons/default to node_modules/@quartzds/generic-icons-default

  3. Register the assets in the <head> section of the HTML pages:

    <html>
      <head>
        <link
          rel="stylesheet"
          media="(prefers-color-scheme:light)"
          href="/quartzds/tokens/core/dist/theme/light.css"
          onload="document.documentElement.classList.add('qds-theme-light');"
        />
        <link
          rel="stylesheet"
          media="(prefers-color-scheme:dark)"
          href="/quartzds/tokens/core/dist/theme/dark.css"
          onload="document.documentElement.classList.add('qds-theme-dark');"
        />
        <link
          rel="stylesheet"
          href="/quartzds/tokens/core/dist/platform/desktop.css"
          onload="document.documentElement.classList.add('qds-platform-desktop');"
        />
        <link rel="stylesheet" href="/quartzds/core/styles/core.css" />

        <script type="module">
          import { defineCustomElements } from '/quartzds/core/loader'
          import { registerIconLibrary } from '/quartzds/core'

          defineCustomElements()

          registerIconLibrary('core', {
            resolver: function (name) {
              return `/quartzds/icons/core/dist/${name}.svg`
            },
          })
          registerIconLibrary('default', {
            resolver: function (name) {
              return `/quartzds/icons/default/dist/${name}.svg`
            },
          })
        </script>
      </head>
      <body class="qds-main">
        <div class="qds-main-section">
          <qds-title layer="main" level="section" icon-name="rocket">
            Get started with <strong>Quartz Open</strong>!
          </qds-title>
          <div class="qds-main-subsection qds-related">
            <qds-title layer="main" level="subsection" icon-name="clock">
              5-minutes tour
            </qds-title>
            <p>
              Discover all the greatness behind the components and styles of
              Quartz Open by following the 5-minutes tour!
            </p>
            <qds-button
              importance="emphasized"
              text="Take the tour"
              icon-name="rocket"
            ></qds-button>
          </div>
        </div>
      </body>
    </html>
Last updated on