A playground for the new Evolution UI directory structure and workflow.
Hello, and welcome to Evolution UI!
The first of its kind, Evolution UI is an open source front-end web framework comprising a collection of innovative and unique web components. These cutting-edge web components are intended to provide a different and enriched online experience and were created by the students of Bov Academy Institute of Programming and Futuristic Engineering (you can learn more about this project and read a write-up on each component by visiting the Bov Academy Blog). This framework is intended to be a hub of web development innovation and we invite everyone to explore their creativity and contribute something innovative of their own to keep the project thriving.
While some of the components are still in development, many are ready for production. The components have been developed with HTML, CSS, Sass, and vanilla JavaScript.
Here, you'll be guided through the steps necessary to get started with Evolution UI. If you have any questions, please don't hesitate to contact the project's maintainers.
This project is compatible with Linux, Unix, Windows*, and Mac OSX operating systems. It requires the following software to be already installed on your system:
Need to update Node.js? Use nvm to manage multiple versions of Node.js on your local machine.
* Running Windows? Jekyll (what we use to build our /docs) does not officially support the Windows operating system, but they do provide special instructions if you want to take a crack at it anyway.
There are several ways to begin using Evolution UI in your project.
You can download Evolution UI as an npm package, which includes the required CSS and JavaScript files.
npm install evolution-uiOr, you can include external links the required CSS and JavaScript files using a CDN.
We recommend you include a link to the CSS in the <head> of your HTML document, and a link to the JavaScript source at the bottom of your file, right before the closing </body> tag.
CSS:
<link rel="stylesheet" href="https://unpkg.com/evolution-ui/dist/evolution-ui.min.css">JavaScript:
<script src="https://unpkg.com/evolution-ui/dist/evolution-ui.min.css"></script>After including the required CSS and JavaScript files, simply add the appropriate HTML to your document to render a component. For example:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>My Project</title>
<link rel="stylesheet" href="https://unpkg.com/evolution-ui/dist/evolution-ui.min.css">
</head>
<body>
<!-- Dot Navigation -->
<nav class="evo_c-dot-navigation evo_c-dot-navigation--flip">
<ul>
<li class="is-active"></li>
<li></li>
<li></li>
<li></li>
<li></li>
</ul>
</nav>
<script src="https://unpkg.com/evolution-ui/dist/evolution-ui.min.css"></script>
</body>
</html>You can find many HTML markup examples and demos on the showcase website for Evolution UI.
Or, you can download the source code in this repository, and build the compiled asset files yourself.
git clone [email protected]:evolution-ui/evolution-ui.git
cd /path/to/repository
npm install
npm run productionThis will install the project and its dependencies on your local machine, and build the compiled asset files from source and output them to the dist/ directory.
If you would like to modify the source of Evolution UI, you will have to install the project’s dependencies after you download, clone or fork the repository. To clone this repository to your local machine and navigate to its location, run the following command(s):
git clone [email protected]:evolution-ui/evolution-ui.git
cd /path/to/repositoryFirst, make sure all of the software listed above is installed on your local machine. The latest stable versions should work fine.
Next, install all of Evolution UI’s required software dependencies.
npm installNOTE: Sometimes you will run into module dependency issues with npm. When you see error messages like Module not found: Can't resolve ... or Cannot find module ..., updating npm (run npm update in your command line) can sometimes fix these issues.
Evolution UI follows the git-flow workflow. Any new work should begin and/or branch from the development branch, which gets periodically merged into master as a somewhat-formal "release". We use commitizen to ensure quality commits, and semantic-release to automate the release process.
A typical workflow would look something like this:
-
Checkout the
developmentbranch and pull in the latest changes:git checkout development git pull --rebase origin development
-
Start the development environment, and navigate to http://localhost:3000/ in your web browser:
npm start
-
You can view any single component in the browser by visiting the following URL pattern:
http://localhost:300/[evolution|standard]/[component-name]/[variant-name].html -
Do work!
-
When you are finished with your feature, bug fix, or whatever, commit your changes using the commitizen CLI (which we have handily aliased as an npm script):
git add . npm run commitWe also use husky to ensure that our tests (
npm run test) run and pass before every commit and push attempt. -
When ready to push a new release, we use semantic-release to automate the process of bumping the version number and publishing the package to npm:
npm run release
In addition to Evolution UI’s source code, we include the source code for the showcase website inside this same repository. The website serves as a showcase of all the UI components in this library. It is built using the Jekyll static site generator, because Jekyll couples nicely with GitHub Pages.
Use Bundler to install all required Ruby gems (the Ruby equivalent of “packages”) specific to the showcase website (located in the /docs directory) by running the following command(s):
cd docs/
gem install bundler
bundle installNOTE: You only need to run gem bundler install if you didn’t already install Bundler on your machine in the previous steps.
Running Windows? Jekyll (what we use to build our /docs) does not officially support the Windows operating system, but they do provide special instructions if you want to take a crack at it anyway.
To build the showcase website, run the following the command(s):
npm run docsThis command will build the latest Evolution UI source and copy the compiled assets into the docs/ directory. Then it builds the Jekyll source files and runs the result in the web browser at http://localhost:3000, and watches for changes as you work and automatically reloads (thanks browser-sync!).
When you are done working on the showcase website, and your commits have been pushed/merged in, you can deploy the latest changes to the showcase website by running the following command(s):
npm run docs:deployPlease follow our detailed guidelines if you would like to make a contribution to this project.
Thanks to all of our wonderful contributors for your hard work!
This project is released under the MIT License.