@davincihealthcare/elty-design-system-vue

@davincihealthcare/elty-design-system-vue

This collection of reusable Vue components is designed to help you easily integrate and maintain a consistent design system across your company's projects. Whether you're building a new application or updating an existing one, these components are ready to be used and customized to match your brand guidelines.

Version Information

The library is available in two major versions:

• Version 1.x.x (default): Stable version with current component implementations
• Version 2.x.x (beta): Next major version with breaking changes and better alignment with the design system

Getting Started

To get started with using these components in your Vue project, follow these simple steps

Installation

First install Tailwindcss following the steps at https://tailwindcss.com/docs/installation/framework-guides

Then install required plugins and the design system package itself:

# Version 1 (default)
yarn add @davincihealthcare/elty-design-system-vue

# Version 2 (contains breaking changes and better alignment with the design system)
yarn add @davincihealthcare/elty-design-system-vue@v2

Required peer dependencies:

yarn add -D tailwindcss postcss autoprefixer @tailwindcss/forms @tailwindcss/typography

Usage

Using the standard foundations

in tailwind.config file

import {EltyTailwindPlugin, EltyTailwindPreset} from '@davincihealthcare/elty-design-system-vue'

module.exports = {
  ...
  content: [..., './node_modules/@davincihealthcare/elty-design-system-vue/**/*.{tsx,js}'],
  plugins: [
    require('@tailwindcss/forms'),
    require('@tailwindcss/typography'),
    EltyTailwindPlugin
  ]
  ...
}

Overriding the standard foundations

in tailwind.config file

import {EltyTailwindPluginWithoutStyle, EltyTailwindPreset} from '@davincihealthcare/elty-design-system-vue'

module.exports = {
  ...
  content: [..., './node_modules/@davincihealthcare/elty-design-system-vue/**/*.{tsx,js}'],
  presets: [EltyTailwindPreset],
  plugins: [
    require('@tailwindcss/forms'),
    require('@tailwindcss/typography'),
    EltyTailwindPluginWithoutStyle
  ]
  ...
}

The Preset way of loading the css was introduced from version 1.18.0

Note: content needs a new entry in the array, alongside other you may already have. You may also change the require with a neater

in main.ts file

import { createApp } from 'vue';
import { EltyVuePlugin } from '@davincihealthcare/elty-design-system-vue';

...

const app = createApp();
app.use(EltyVuePlugin);


...

remember to use the related vue plugin (it will install form validation rules)!

// Import the component you need
import { ElButton } from '@davincihealthcare/elty-design-system-vue';

Now, you can use the imported component in your templates:

<template>
  <div>
    <ElButton label="Click me" @click="onClick" />
  </div>
</template>

<script lang="ts" setup>
import { ElButton } from '@davincihealthcare/elty-design-system-vue';
const onClick = () => {
  window.alert('click');
};
</script>

Tech stuff and instructions 🔥🔥

• EltyTailwindPlugin contains some custom css to be applied on forms and so on.
• EltyTailwindPreset contains the base style for the elty design system. Exported as a preset, and not as a plugin so that it can be easily overridden by the user application
• EltyVuePlugin contains the vee-validate rules for the inputs

As it has been set the following as peer dependencies

• @tailwindcss/forms
• @tailwindcss/typography
• vee-validate
• vue

please check for compatibility issues if you experience something strange

Style Configuration (style.cjs):

This section handles the styling for your Vue component library, leveraging Tailwind CSS for efficiency. Here's a breakdown of the process:

1. Base Styles (src/style.css):

   This file is where you define the foundational CSS styles that you want to use in conjunction with Tailwind. Focus on including essential styles that are unlikely to change frequently. This helps maintain a clean separation between your core design principles and the dynamic nature of Tailwind classes.

2. Tailwind Processing (yarn build): Running yarn build triggers postcss, a CSS preprocessor. It scans src/style.css and replaces Tailwind directives (@apply, etc.) with actual CSS classes based on your Tailwind configuration. The processed output is saved as dist/style.css.

3. CJS Conversion (yarn build-prejss): A separate script (potentially yarn build-prejss) is called during yarn build. It takes the processed CSS file (dist/style.css) and generates a CommonJS module (dist/style.cjs). This format is necessary because your src/tailwind.plugin.ts file will import it (explained below).

4. Tailwind Integration (src/tailwind.plugin.ts): This file defines the Tailwind plugin used within your library. It imports the generated dist/style.cjs file. When you integrate your library into another project that has Tailwind installed, this import will work seamlessly because the library will include the compiled style.cjs file.

   Key Points:

   You don't need to worry about providing dist/style.cjs separately. It's included in the built library package. Your library's components can leverage Tailwind classes by referencing them directly.

Breaking changes coming in v2 (likely Jan 2025)

• button v2 will have a different interface
• remove id from input which is useless and just use name prop
• from IDs will be delegated to the parent https://davincisalute.slack.com/archives/C03HLJGN04S/p1720704672112299

Migration instructions are available in MIGRATION.md