patricia-ui-components

This is a collection of UI components that will be used across all of Patricia's platforms to ensure consistent styling.

Check out the Usage Guide

Project setup

npm install

To demo or view your component

Import and use your component in demo/App.vue. Then run

npm run serve

Export your component

You have to expose your component in main.js for it to be of any use. Simply import it and add it to the list of exports

import AwesomeComponent from 'path/to/AwesomeComponent.vue'
...

export { ... AwesomeComponent ... }

Customize the theme

To support custom themes, this library implements and uses a default theme, containing default values for properties such as colors, fontSizes, screens (can be used as screen sizes and breakpoints), and roundness (can be used for border-radius setting), and dark (used to indicate whether the theme is in dark mode or not) so if no property is specified, it will apply the default theme

Using the theme in your project

You can do this in any project by attaching the theme object to the root Vue object of such project.

For example, in a Vue CLI project, you could do:

import Vue from 'vue';
import App from './path/to/App.vue';

// other configs if any

Vue.prototype.$theme = {
  colors: {
    primary: {
      default: '#0276FF',
      base: '#032041',
      dark: '#0050AF',
      pale: '#E8F7FF',
      light: '#479BFF',
    },
    danger: {
      default: '#CC2E2E',
      dark: '#A10000',
      light: '#D75C5C',
      pale: '#FFF3F3',
    },
  },
  fontSizes: {
    heading: {
      1: '48px',
      2: '40px',
      3: '32px',
      4: '20px',
    },
  },
  roundness: {
    2: '2px',
    5: '5px',
  }
};


new Vue({
  render: h => h(App),
}).$mount('#app');

In a gridsome project, follow the guidelines here https://gridsome.org/docs/assets-scripts/

//main.js

import DefaultLayout from '~/layouts/Default.vue';

export default function(Vue) {
  // Set default layout as a global component
  Vue.component('Layout', DefaultLayout);

  //Set up the color theme
  Vue.prototype.$theme = {
    colors: {
      primary: {
        default: '#0276FF',
        base: '#032041',
        dark: '#0050AF',
        pale: '#E8F7FF',
        light: '#479BFF',
      },
      danger: {
        default: '#CC2E2E',
        dark: '#A10000',
        light: '#D75C5C',
        pale: '#FFF3F3',
      },
    },
    fontSizes: {
      heading: {
        1: '48px',
        2: '40px',
        3: '32px',
        4: '20px',
      },
    },
    roundness: {
      2: '2px',
      5: '5px',
    }
  };
}

You can change the theme dynamically and all the components will automatically update to reflect the new/updated theme A theme usually contain the following properties:

• dark (boolean): whether this is a dark theme or light theme.
• roundness (object): roundness of common elements, such as buttons.
• colors (object): various colors used throughout different elements.
  • primary - variants of colors for your app, usually shades of the brand color.
  • danger
  • success
  • pending
  • font
• screens (object) - screen sizes and breakpoints
• fontSizes (object)

NOTE: You can omit any key and it will fallback to the default. Hence, for most situations, you only need to specify some key parts of the theme.

Writing your components to factor in the theme

You might need to use several colors while writing your components, especially to set states: primary, success, danger etc. Please note the following.

A mixin has been written at @/mixins/theme

• Import and use the colors mixin as such in your component:

import theme from '@/mixins/theme';

export default {
    mixins: [theme],
    ...
}

• Write your CSS/SCSS to use the css variables instead of hard-coded colors, especially for the colors included in the palette. The css variables follow the format --primary or --success (for the default key) and --primary-dark or --success-pale for the other keys inside each palette.

.btn {
  &-error {
    background-color: var(--danger);

    &.loading {
      background-color: var(--danger-light);
    }
  }
}

Or CSS

.btn-error {
  background-color: var(--danger);
}

.btn-error.loading,
.btn-error.disabled {
  background-color: var(--danger-light);
}

IMPORTANT NOTE

Do not try to use scss color functions with the css var() key. It won't work because the css variables aren't available until runtime in the browser.

Compiles and minifies the component library for production deployment

npm run build-lib

This generates several files in the dist folder

Run your unit tests

npm run test:unit

Lints and fixes files

npm run lint

Customize configuration

See Configuration Reference.

StoryBook

We use Storybook to visualize our components and styles. Run storybook to interact with components.

npm run storybook

Remember to import these styles to your stories to enable Global utility classes.

import '@/assets/scss/tailwind.css';
import '@/assets/scss/global.scss';

Publishing to npm

1. npm run build-lib : This builds the pakage
2. Increase the version number
3. npm login username is patricia_engineering and email is [email protected]. Contact the Team lead or Engineering Manager for the password
4. npm publish --access public : To publish the package