This guide will walk you through the process of setting up and using the design system in your host application.
Please see README.dev.md for developer focused documentation.
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.jsormain.jsorgatsby-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';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.
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
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;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 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 storybookIf 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.
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=falsethen 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=trueor leave it unset (default), you can use thedist/wings.cssstatic site file instead. You can avoid FOUC (flash of unstyle content) this way!
set the use static css env var
tsdx build
USE_STATIC_CSS=false tsdx build