@crossmasters/ui v0.5.0

Cross Masters UI Components

Cross Masters UI Components is a Vue 3 component library that utilizes Tailwind CSS. While this library is primarily intended for internal use by the Cross Masters development team, anyone is welcome to leverage its capabilities if they find it useful.

Getting Started

To get started with Cross Masters UI Components, follow these steps:

1. Make sure you have the necessary dependencies installed. You need at least Vue 3 (Vue 2 is not supported) along with Tailwind CSS, PostCSS, and Autoprefixer.

2. Install the library in your project by executing the following command:

   npm i @crossmasters/ui

3. In your main application file (typically main.ts or main.js), where you call app.mount('#app'), import the library's CSS file. Don't forget to import your main CSS file as well. The library file must be imported first because you want to be able to customize the library theme via your CSS. Here's an example of a main.ts file:

   import { createApp } from 'vue';
   import { createPinia } from 'pinia';
   
   import App from './App.vue';
   import router from './router';
   
   import '@crossmasters/ui/dist/styles.css'; // Import the library CSS file first
   import './style.css'; // Import the main CSS file for your app second
   
   const app = createApp(App);
   
   app.use(createPinia());
   app.use(router);
   
   app.mount('#app');

   Note: Normally, you would import @tailwind directives for each of Tailwind’s layers. However, do not import @tailwind base in your app, as this is already imported via the component library. Importing it again would cause conflicts in your CSS rules.

4. In your Tailwind CSS configuration file (tailwind.config.js), you need to add all the library custom variables. This is added via the theme.extend block. Also you need to include the library files in the content section of config to correctly generate all the Tailwind classes for you. This is the current version that needs to be included (note: in future versions, we want to handle this via a plugin):

   module.exports = {
     content: [
       './index.html',
       './src/**/*.{vue,js,ts,jsx,tsx}',
       'node_modules/@crossmasters/ui/dist/**/*.{mjs, js,jsx,ts,tsx}',
     ],
     plugins: [],
     theme: {
       extend: {
         colors: {
           primary: 'rgb(var(--twc-color-primary) / <alpha-value>)',
           danger: 'rgb(var(--twc-color-danger) / <alpha-value>)',
           success: 'rgb(var(--twc-color-success) / <alpha-value>)',
           warning: 'rgb(var(--twc-color-warning) / <alpha-value>)',
         },
       },
     },
   };

5. You are now ready to use Cross Masters UI Components!

Usage

Importing Individual Components

To use the provided components, import them into your Single-File Component (SFC). This is the recommended approach and is required in most of our internal projects.

After importing the component, use it as per its specific requirements.

Example:

<script setup lang="ts">
import { CmButton } from '@crossmasters/ui';
</script>

<template>
  <div class="greetings">
    <cm-button
      variant="primary"
      text-color="white"
    >
      This is our button
    </cm-button>
  </div>
</template>

Registering Library Components Globally

While it is possible to register library components globally, this approach is not recommended as it complicates tree-shaking and may cause difficulties in maintaining larger applications. Use this approach only if you have a clear understanding of its implications.

TODO

Theming

The library does have a neutral default styling. You might need to adjust the theme to fit your project requirements. This is possible by changing the values for provided css variable. Set new values in your main css file.

If you want to use these CSS variables in your app directly, you can do it. You have to include the definition of variables within your tailwind.config.js file. But it is not recommended to do it with the --twc prefix. Instead, use the --cm prefix. The --twc variables are used to calculate final values by Tailwind and in our components. Therefore it is easier to use the full variables with --cm prefix.

Example: Having the --twc-color-primary value of 255 115 179 then --cm-color-primary is rgb(255 115 179/1).

p {
  text: var(--cm-color-primary); /* you can do this */
}

p {
  text: rgb(var(--twc-color-primary) / 1); /* instead of this */
}

Dark mode

TBD

Development

To contribute to the development of Cross Masters UI Components, follow these steps:

• Clone the repository
• Install the dependencies using npm install
• Start the development server with npm run dev