@testifysec/wings

v1.2.2

Published

9 days ago

wings: A design system by TestifySec

Downloads

139

0High
0Medium
0Low

georgesdugue

kriscodeman

design design-system react tailwindcss testifysec

Wings Design System Usage Guide

This guide will walk you through the process of setting up and using the design system in your host application.

Developer Documeentation

Please see README.dev.md for developer focused documentation.

Setup

To set up the design system in your host application, follow these steps:

You can install the design system package using your package manager of choice. For example, if you're using npm, you would run npm install @testifysec/wings.
You can install the package easily if you add it as a subtree. You can then add it to your workspaces and/or import it by file, e.g.; in your host pacakge.json you can add this to your dependencies:

{
    #... your other pacakage.json stuffs
    "workspaces: {
         "subtrees/design-system"
    },
    #... or...
    "dependencies": {
        "design-system": "file:../design-system",
    }
}

Import the design system into your application. This can typically be done at the top level of your application, in a file such as App.js or main.js or gatsby-browser.js. Here's an example of how to do this:

// first you should import the css
import '@testifysec/wings/dist/wings.css';
// then import what you need from the design-system component library 
import { Theme } from '@testifysec/wings';

Strap on some wings

To bootstrap the design system in your application, you'll need to wrap your application with a Theme component. This will provide your application with base styles, light/dark colors, fonts, and a grid system. Here's an example:

import { Theme } from '@testifysec/wings';

function App() {
  return (
    <Theme>
      {/* Your application code here */}
    </Theme>
  );
}

export default App;

Review the (Storybook Page on Layout)[] for more details.

Example

At any time, you can check out the example provided in /example for a example of quickly bootstrapping the project into a web app.

Follow the readme here

Using Components

The design system provides a number of components that you can use in your application. For example, you might use a Header, Body, and Footer to provide a consistent, on-brand navigation experience. Here's an example:

import { Theme, Header, Body, Footer } from '@testifysec/wings';

function App() {
  return (
    <Theme>
      <Header />
      <Body>
        {/* Your application code here */}
      </Body>
      <Footer />
    </Theme>
  );
}

export default App;

Setting the Body

To match the gutters of the design system, you can set the body of your application with container-x and container-y. You could also use a <Body> component. Here's some examples:

import { Theme, Header, Body } from '@testifysec/wings';

function App() {
  return (
    <Theme>
      <Header/>
      <div className="container-x container-y">
        {/* Your application code here */}
      </div>
        {/* -or- */}
      <Body>
        {/* Your application code here */}
      </Body>
    </ Theme>
  );
}

export default App;

We hope this guide helps you to effectively use the design system in your application. If you have any questions or run into any issues, please don't hesitate to reach out to us.

Storybook

Storybook is a tool that we use for developing and showcasing the components in our design system. It allows us to create and test components in isolation, which makes it easier to develop and debug our components.

If you have the source code for the design system, you can run Storybook locally. To do this, navigate to the root directory of the project in your terminal and run the following command:

npm run storybook

If you are adding this to your project as a subtree, we recommend wiring this up to your root package.json with this script:

{
    "scripts" : {
        "start:storybook": "npm run storybook -w design-system"
    }
}

This will start Storybook and open it in your default web browser.

In addition to running Storybook locally, we also provide a short-lived version of Storybook with each pull request. This allows for easy review and UAT of the design-system changes when changes are made.

In addition to running Storybook locally, we also provide a live version of Storybook that is updated with each change. This allows you to see the latest changes to the components without having to run Storybook locally. You can find the live version of Storybook at the following URL:

https://judge-design-system.netlify.app/

We hope that Storybook will be a useful tool for you as you use and contribute to our design system. If you have any questions about using Storybook, please don't hesitate to reach out to us.

Including Styles

There are many ways to ship styles, including with CSS-in-JS. TSDX has no opinion on this, configure how you like.

We have implemented two ways with our design-system:

CSS in JS: if you set USE_STATIC_CSS=false then our design-system JS will auto-load the css into the host application for you when built.
Static CSS (best): if you set USE_STATIC_CSS=true or leave it unset (default), you can use the dist/wings.css static site file instead. You can avoid FOUC (flash of unstyle content) this way!

To use static CSS

set the use static css env var tsdx build

To use dynamic injection

USE_STATIC_CSS=false tsdx build