The Moxi Design System is a framework utilizing TailwindCSS and StencilJS to provide a CSS foundational framework combined with a library of universal Javascript components to use in any project with any framework you desire.
The goal is to create this framework to the spec of our design team and committing to the continued growth of this system moving forward.
The project uses Vuepress as a means to write documentation as you develop. When the system is built, Vuepress is compiled to the docs directory to be accessed via Github pages. This project also uses yarn over npm.
npm install yarn -g
- Fork and then clone the project locally.
- Inside the cloned direcrory run
yarn install. - After the dependencies are installed run
yarn devto start the development Vuepress server.
You can now access the site at http://localhost:8080.
Because of relationship between Vuepress, TailwindCSS, and Stencil, simply running yarn dev will result in more changed files than you might be prepared for. To make the multiple framework environment work, they all react off of changes to one another.
If your only goal is to add or edit documentation, please do the following:
In your terminal run yarn docs:dev. This will ensure that only Vuepress is listening to changes resulting in the changes only being documentation and not dynamic Javascript files or TailwindCSS alterations.
The development site is located under the vuepress directory. To learn more about Vuepress and it's paradigms, please read the documentation here.
The basics are very straight forward. The site is powered by Markdown files. Add and edit folders and .md files as needed for documentation and development.
You can develop the component in Vuepress then write the documentation around it when ready.
All of the StencilJS components are located in the src directory. There is a generator to stub a new component: yarn generate mx-{name of component}. All of the components are prefixed with mx-. For example, the input component is called mx-input which is essentially the tag name <mx-input />.
You can read more about Stencil, it's lifecycle methods, property handling, etc at https://stenciljs.com/docs/introduction.
The TailwindCSS code is located under src/tailwind. The configuration file is located in the root of the directory as tailwind.config.js.
You can read more about TailwindCSS here.
We are not using the Shadow DOM for the Stencil components and are not using the CSS paradigm they provide. The reason is that the CSS for this project needs to also support Ruby based view components. You can read more about them here: https://viewcomponent.org/.
There's no reason to write and maintain this CSS in two places so the TailwindCSS implementation will be the source of truth for our component styling.
Under src/tailwind you'll see directories like mx-input and mx-button. Those SASS directories and files are included in the styles.css file. SCSS is transpiled to CSS immediately thanks to PostCSS.
From your project run yarn add @moxiworks/mds or npm install @moxiworks/mds depending on your package manager.
At your entry point add the following code:
import { applyPolyfills, defineCustomElements } from '@moxiworks/mds/loader';
// Bind the custom elements to the window object
applyPolyfills().then(() => {
defineCustomElements();
});StencilJS provides a loader which dynamically "tree-shakes" the code as needed. So, for example, the bundle for the mx-input won't be included in your bundle until you've written code in one of your views like:
<mx-input label="Placeholder & Left Icon" left-icon="ph-apple-logo" />StencilJS has a bunch of documentation around integrating these types of components into most popular frameworks - including vanilla Javascript. You can read more about that here: https://stenciljs.com/docs/overview