Instructions

The Fifth World website uses the Fifth World Design System, and though that site serves as the hub of our community, it does not represent its entirety. As an open source shared universe, we hope you’ll use it to develop your own projects. Our API and this design system can help you integrate your project seamlessly with the larger Fifth World ecosystem.

Using this in your own project

First, make sure that you understand the foundations that we build the design system on, in particular our approach to progressive enhancement. Each page should use one of our templates — usually the standard template. Load the styles necessary by adding these tags to the <head> of your page:

<link rel="stylesheet" media="all" href="https://cdnjs.cloudflare.com/ajax/libs/cropperjs/1.5.7/cropper.min.css" crossorigin="" />
<link rel="stylesheet" media="all" href="https://design.thefifthworld.com/v1/1/0/style.css" crossorigin="" />

Then, you’ll usually want to load the JavaScript so that you can have the client-side enhancements that each component offers by adding this tag right above the </body> closing tag (though if you know that you haven’t used any components that have client-side enhancements, you could leave this out to improve performance):

<script src="https://design.thefifthworld.com/v1/1/0/bundle.js"></script>

Next comes the hard part: actually developing your project! Use components to fill that page with the content unique to your project.

Contributing to the design system

If you develop your own project with this design system — or if you just want to help improve the Fifth World — you might want to contribute fixes or whole new features to the design system. We really appreciate such contributions! You can find the source code for this design system on Github. If you’ve never contributed to a Github project before, you might want to take a look at the Hello World Github Guide, which walks you through a lot of the basics, like what repositories, commits, and branches mean, and how to use them.

To contribute to our design system, you’ll need to run it locally first. You will need to have Node.js to do this. Once you have Node installed, you can go to a command prompt and run the following commands from the directory you’d like to work from:

mkdir thefifthworld
cd thefifthworld
git clone https://github.com/thefifthworld/design.git
cd design
npm install
npm start

Next, check out the develop branch and create a new branch from that. Use this format for your branch name: TYPE/NAME-NUM-DESC.

Element	Notes
`TYPE`	One of the following: `bug` if your branch addresses a bug or problem. A bug fix doesn’t add new functionality to the system, it just fixes something broken. `feature` if your branch adds a new feature to the system. Even if you believe the system lacking this feature constitutes a huge oversight, it counts as a new feature, not a bug fix. `doc` if your branch adds or fixes documentation around the system (for example, these instructions). `system` if your branch addresses how the system works (e.g., dependency updates or how the design tokens are parsed).
`NAME`	Your Github username.
`NUM`	If your branch addresses a reported issue, put the number for that issue in the branch name.
`DESC`	A single word or a very short phrase that describes what the branch does or addresses. Write it all in lowercase, with dashes to replace spaces.

Example: I write these instructions in a branch called doc/jefgodesky-instructions. It deals with documentation, I have the Github username jefgodesky, and we don’t have a Github issue for writing these instructions, so I have no number to refer to.

Next comes the hard part: actually making the changes you’d like to see. Run the design system locally to make sure that your changes work and don’t cause any unexpected side effects. When you feel confident that you’ve finished it, push your branch and make a pull request to merge your branch back into the develop branch. Pull requests create a space for you and the people who administer the design system project to collaborate on your changes. Sometimes they’ll approve your changes right away and the process will go very quickly. Other times they might have comments, questions, or suggestions for you. We’ll work together to make sure that we make the best design system we can.

Once approved, your work gets merged back into the develop branch. When we’ve gotten enough changes, we merge the develop branch into the main branch to create a new release — at which point, your contribution officially becomes part of the Fifth World Design System!

Finding help on Discord

If you want to use the design system for your own project or make contributions to the design system itself but you don’t have an account as a member of the Fifth World website, you definitely deserve one! Let us know and we’ll make sure that you get an invitation. Yuor membership will include access to the official Fifth World Discord server. The #design channel there exists for people who have questions or comments about this design system. We’ll happily answer all of your questions there and help you through the process.