Skip to content

Creating components

Workflow creating or changing the component

Work on creating or edition of the component should always start with defining the requirements and describing the task, which is the beginning of the following process:

  • creating a task and preparing its description;
  • estimation of the task;
  • granting priority and acceptance for implementation;
  • creation of a git branch for the task;
  • task delivering - creation or modification of component files, documentation and tests;
  • pull request and code review;
  • verification of the correctness of the visual layer of the component - checking with the project in Figma
  • possible corrections and accepting - merging to develop branch.

Naming conventions

Naming components affects their location in the structure of the component library and affects their subsequent use. Two types of notation are used:

  • Pascal Case - for the names of the component folders, component file and component test file
  • Kebab Case - for documentation file names and in the use of a component in the Template of another component, e.g. <template><hello-world /></template>;

Other principles of naming convention:

  • the Vue component may consist of one word, but its unique name (property name) must consist of at least two words in the Pascal Case notation, e.g. a file Avatar.vue he will have property name UiAvatar;
  • the above principle affects the use of a component in other components, because it will use kebab case notation, i.e. <avatar />;
  • all component names must be unique in the library of components regardless of which atomic design group they function;
  • the name of the component should take into account the naming used in the design files in fig;
  • each component has in its catalog the Index.ts file responsible for exporting the Vue component;
  • the components are grouped according to the Atomic Design approach, and each group has in their catalog the Index.ts file responsible for the export of all components of a given group;
  • all components from the Atomic Design groups are imported and installed in the application using the src/index.ts file;
  • each unit test file for the component is in the component folder I take the name ComponentName.test.ts;
  • each documentation file takes the name component-name.md and is in the folder of the appropriate group of Atomic Design components in docs/components;
  • each component using the Tailwind class has a ComponentName.bosons.ts file in which Boson (globally defined) objects are defined to keep information on assigning Tailwind classes to props.

Component file

Component file:

  • located in the catalog `src/components/(quarks|protons|atoms|molecules|organisms);
  • it created using composition api and TypeScript;
  • always contains the name of the component (property name);
  • is exported and then can be imported in other components;
vue
<template>
  <div>Content</div>
</template>

<script lang="ts">
import { defineComponent } from 'vue'
export default defineComponent({
  name: 'UiComponentName'
})
</script>
ts
import ComponentName from './ComponentName.vue'
export default ComponentName

WARNING

quarks instead of .vue are importing .ts because the quarks do not have a layer of presentation, and only the part responsible for logic. Quarks are composables.

Test file

Test file

  • is located in the catalog src/components/(quarks|protons|atoms|molecules|organisms);
  • the test file is a must-have part of the component, i.e. that the developer, creating a component, should immediately provide unit tests of the component;
  • tests are described here

Documentation file

Each components must have a documentation file in which it will be in a clear and accurate way:

  • describe the allocation and principle of the component;
  • list props, slots end events;
  • show an example code, allow it to be easily copied and paste it in the application;

The documentation is created in the Markdown syntax and using dedicated components enabling the preview of the component. Auxiliary components are found in the src/components/ui folder. We distinguish the following auxiliary components:

  • Preview - a component of previewing components;
  • Item - a component supporting components in the preview by adding information about the component option;
  • ItemSlot - description of the component slot;
  • ItemEvent - description of the component event;
  • ItemProp - description of the component props;
  • ItemColor - color description for system design;
  • ItemIcons - list of icons;
  • ItemReturn - lists the elements returned in composables (kwarki);

Sample documentation of components can be viewed in the component HelloWorld. The effect of the UiTeColor component is visible in the Tailwind documentation.

INFO

Auxiliary components are installed only in the documentation and do not constitute part of the component library or application.

Assets

Proper application, component library and documentation should use the same graphic file base such as icon file, pictures, avatars, etc.. All these files should be placed in the src/assets directory. Files that will only be used by documentation should be placed in the docs/assets folder.

WARNING

Importing svg files in components differs from importing in documentation files. This should be paid special attention when creating a new component. To see the difference in importing files from the component and in the documentation you need to see components and documentation for Icon and Avatar.