koodoo-question-journey-design-system v2.1.0

Koodoo Q&A User Journey Design Guide

Introduction 🎬

This guide aims to outline the technologies, tools, processes, and design patterns software engineers should follow when designing a question and answer user journey in the form of a web application.

Assumptions and requirements ✅

Design concepts 🖌

You'll be assumed to be familar with:

• Single Page Applications

• Modern Web Development Architecture

• Client-Server Architecture

• Continuous Integration

• Atomic Design

Software Processes 🎰

You'll be assumed to be comfortable with:

• Using version control using Git

• Using structured formats to denote change e.g. Semantic Versioning and Conventional Commits

• Writing unit tests

• Structuring your code in a modular style

Coding standards 🔢

You'll be expected to try and adhere to:

• Functional programming style

• Clean Coding Style

• Modern Javascript

Tools, libraries, languages and frameworks 🛠

You'll need to be comfortable using:

• Node.js (Version 12) and npm (Version 6) for builds and dependency management

• React.js (Version 16) as the UI framework

• Webpack (Version 5) for bundling UI assets

• Tailwind CSS for styling

• Jest for unit testing

• Playwright for automated UI testing

• Github for source control

Code Formatting ⛩

In order to allow maixmum efficiency and ease of standardisation we leverate these tools for code formatting

• Prettier

• ESlint

Hardware 🚜

We aim for OS independent builds and development enviornments to allow developers the freedom of working on any machine. The only requirement is to strictly avoid using any OS specific dependencies, libraries, tools, processes or packages.

Development 💻

Installing dependencies 👨‍👩‍👧‍👦

0. Clone the repository by running: git clone https://uri-TBD.git
1. Install the node dependencies by running : npm install

If you wish to install any other external dependencies, these should be formally reviewed and requested prior to being being included as part of the project. Feel free to view the following template for how to present these requests:

• Package name : my-awesome-package.js
• Github : https://link/to/repo.com
• Description: Helps with doing useful stuff
• Reason: Because it will be facilitate delivery of feature x
• Evidence of Due dilligence: The package is fequently maintained, has rich documentation, is used, and has no security or vulnerability alerts.

Running the application locally 🏃‍♂️

0. In order to start the application on your local machine on port 3000, run: npm run start. This will start a locally running instance of webpack dev server and host the application on http://localhost:3000

Terminal Output

Browser Output

Viewing the components 🔍

A Storybook build is included to facilitate viewing the componets in isolation. In order to do this run: npm run storybook which will start a local instance of storybook on port 6006 e.g. http://localhost:6006/

Running the tests 🧪

You may run: npm run test to run the unit test suite.

Example output

You may also run automated browser tests when a locally running instance is running, by executing: npm run e2e (this assumes you have already ran npm run start)

Running the formatter 👔

• npm run lint for code linting
• npm run format for code formatting

This will go through the files in the repository and ensure that code formatting rules are being met.

Committing and making changes ➡️

You should be familiar with the GitHub flow.

In order to make change, first ensure you are working from the latest master branch.

• git pull master

Then, create your working branch e.g.

• git checkout -b [your-branch-name]

Next

• Make your code changes
• Ensure tests have been written, and all tests are passing
• Ensure lint and formatting rules have been met
• Add the change files to your branch by running:
• git add .

Then, to commit, run:

• npm run cm

Which will guide you through creating a conventional commit

• If all goes well, push up your change branch to the remote and submit a pull request against master.

Creating a question ❓

See the example question component

In order to create a question you can simply copy this template, which has some metadata about the question written in the following structure, and the defined input component for the specific question e.g.:

// src/components/Questions/your-new.component.js
import React from "react";
import TextInput from "../TextInput/text-input.component";

export const metadata = {
  key: "questionKey", // key used to denote the question (must be unqiue)
  header: "Your question title", // the heading text content
  title: "What is your question?", // the question text content
  desc: "Fill this content in", // description text content
};

// Input component
export const Input = ({ handleChange, value }) => (
  <TextInput
    id="your-new-input"
    onChange={(e) => handleChange(metadata.key)(e.target.value)}
    value={value}
  />
);

export default {
  metadata,
  Input,
};

and this is added to the app by then importing the module in the App file

import React, { useState } from "react";
import QuestionShell from "./components/QuestionShell/question-shell.component";
import YourNewQuestion from "./components/Questions/your-new.component";

const questionSet = [YourNewQuestion, ...OtherQuestions];

and adding the question the questionSet array. (See the screenshot above to see how these fields map to the rendered screen)

Styling 🎨

See tailwind docs for full specs, but you can simply edit the classes in any component with the desired tailwind class e.g.

Take this button component, you change the button colour by editing the className attribute in following code with the right tailwind class for your desired colour:

From Blue: 🔵

const PrimaryButton = () => {
  return (
    <button
      className={
        "bg-blue-400 hover:bg-blue-200 focus:bg-blue-600"
      }
    >
    </button>
  );
};

To Green: 🟢

const PrimaryButton = () => {
  return (
    <button
      className={
        "bg-green-400 hover:bg-green-200 focus:bg-green-600"
      }
    >
    </button>
  );
};

Validating user input 🚨

You may export a validate function from your components as such:

// src/components/Questions/first-name.component.js
export const validate = (value) => {
  if (!value) {
    return {
      isValid: false,
      message: "This value is a required",
    };
  }

  return { isValid: true };
};

export default {
  metadata,
  Input,
  validate,
};

This function takes in the data entry value from the user and should return an object:

{
      isValid: false,
      message: "This value is a required",
}

This field will be used to conditionally display the error states upon user entry according to the specified validation logic.

Building the application for production 📦

In order to generate a production build and produce the assets used for our live app you may run: npm run build

This will use webpack to generate the production bundle (JS, html, css) in a directory called build

Build Pipeline and Releases 🚄

TBD

Creating a release 🚢

• Run: npm run release to create a release tag.

Designs and UI Assets 🖌

Zeplin 👨‍🎤

link to Zeplin TBD

Questions and general support 🤔

You may contact our development team via Slack TBD or via email TBD.