@dcodegroup-au/dsg-vue

DCODE Style Guide (DSG) - Vue

DCODE/Digital Style Guide (DSG) - Front-end Vue 3/TailwindCSS package for UntitledUI, written in Typescript and Vue format. This package is an extensible set of Tailwind Plugins and Vue components that match UntitledUI Figma design systems. To get started, view the Storybook documentation.

Install

NPM Package

For standard Vue 3 project installations, you can install the dsg-vue package using any of the following commands below.

pnpm i -D @dcodegroup-au/dsg-vue

GitHub Repository

pnpm i -D https://github.com/DCODE-GROUP/dsg-vue#main

Local Directory

pnpm i -D /path/to/dsg-vue

(Optional) Vue 2 Compatibility

For projects that still have Vue 2 components, you can install extra dependencies to ensure compatibility. For more information view the migration build here.

Step #1: Install NPM Packages

# Install: Vue 3 & Compatibility Libraries
pnpm i @vue/compat vue

# Install: Vue 3 Compiler
pnpm i -D @vue/comopiler-sfc

# Remove: Vue 2 Template Compiler
pnpm remove vue-template-compiler

Step #2: Update Build Configuration to use @vue/compat

Webpack Configurations

// webpack.config.js
module.exports = {
  resolve: {
    alias: {
      vue: '@vue/compat'
    }
  },
  module: {
    rules: [
      {
        test: /\.vue$/,
        loader: 'vue-loader',
        options: {
          compilerOptions: {
            compatConfig: {
              MODE: 2
            }
          }
        }
      }
    ]
  }
}

Vite Configurations

// vite.config.ts
import { defineConfig, UserConfig } from "vite";

export default defineConfig(({ command, mode }) => {
  return {
    resolve: {
      alias: {
        vue: '@vue/compat'
      }
    },
    plugins: [
      vue({
        template: {
          compilerOptions: {
            compatConfig: {
              MODE: 2
            }
          }
        }
      })
    ]
  } satisfies UserConfig;
});

Usage: Tailwind Configuration

To configure the Tailwind CSS portion of the package, you will need to create a tailwind.config.ts file in the root of your project. Then you will need to extend the dsg-vue Tailwind configurations/plugins to match your project Figma/design guidelines.

// # Import: Types
import type { Config } from "tailwindcss";

// # Import: DSG Tailwind Plugin
import { DsgTailwindPlugin, DsgColourConfig, DsgFontFamilyConfig } from '@dcodegroup-au/dsg-vue/tailwind';

// # Extend: DSG Color Config
const ColourPalette = {
  ...DsgColourConfig,
};

// # Extend: DSG Font Family Config
const FontFamily = {
  ...DsgFontFamilyConfig,
};

export default {
  content: ['./src/**/*.{vue,js,ts,jsx,tsx}', './demo/**/*.{vue,js,ts,jsx,tsx}'],
  theme: {
    extend: {
      colors: ColourPalette,
      fontFamily: FontFamily,
    },
  },
  plugins: [...DsgTailwindPlugin],
} satisfies Config;

Usage: Vue Components

To use the Vue components within the package, you will need to import them directly into your Vue components. The components are exported as named exports from the dsg-vue package.

<template>
  <div>
    <DsgInput
      label="Email Address"
      type="email"
      placeholder="[e-mail]"
      name="email"
      classes="form-input username"
      icon="mail-01"
      tool-tip="This is your username or email address."
      :has-tooltip="true"
      autocomplete="false"
      ref="forms.email"
    />
    <DsgButton 
      label="Login"
      type="submit"
      width="full"
      :preventDefault="true"
      theme="brand"
      aria-label="This is an aria-label"
      classes=""
      @button-clicked="loginClicked"
    />
  </div>
</template>

<script setup lang="ts">
// # Import: DSG Vue Components
import { DsgButton, DsgInput } from '@dcodegroup-au/dsg-vue';

</script>

View more on each component in the Storybook documentation.

Usage: CSS

To import the styling generated from the dsg-vue package, ensure you import the CSS file into your main entry file (e.g. main.ts, app.ts, index.ts). This will ensure that the Tailwind CSS classes and the DSG Vue components are styled correctly.

// # main.ts / app.ts / index.ts

// # Import: Vue
import { createApp } from 'vue';

// # Import: DSG Vue CSS (NPM Install)
import '@dcodegroup-au/dsg-vue/dsg-vue.css';

// # Import: DSG Vue CSS (GitHub/Local Install)
import 'dsg-vue/dsg-vue.css';

Tailwind Plugin/Component

The dsg-vue package contains a set of Tailwind CSS plugins and components that allow you to extend the TailwindCSS default theme and also overrides certain classes to have styles matching the UntitledUI design system; always refer to the Figma Design as the source of truth.

Tailwind Plugins

Within the dsgTailwind export, you will find a list of Tailwind CSS plugins that are used to extend the default Tailwind CSS theme. These plugins are used to add additional classes to the Tailwind CSS framework that match the UntitledUI design system. This includes:

• DsgRadiusPlugin
• DsgTypographyPlugin
• DsgGradientPlugin
• DsgBackdropBlurPlugin
• DsgShadowsPlugin
• DsgFocusRingsPlugin

To exclude or only use specific plugins, you can import them directly from the dsg-vue package and add them to the plugins array in the tailwind.config.ts file instead of using the dsgTailwind export as shown above.

NOTE: Each of the individual plugins are not extensible/customisable and are only used to add classes to the Tailwind CSS framework.

Tailwind Components

Within the package, there are also two extensible components that house the theme configurations as exports for customisation. These components are:

• DsgColours
• DsgFontFamily

To extend these components, you can import them directly from the dsg-vue package and add them to the theme object in the tailwind.config.ts file as shown above.

UntitledUI - Figma Design System

The dsg-vue package is built to match the UntitledUI Figma design system. Each project should have a design system setup based off UntitledUI which serves as the source of truth for design. Reach out to designers or relevant person for access.

For more information on the base Design System Template check out Figma folder for the designated project or at the following link:

• UntitledUI - Pro Version Demo