A design system for the University of Iowa.
See the documentation at https://uids.brand.uiowa.edu.
The documentation uses Vue.js. You can build and run a local version to aid in development.
Node Version Manager (NVM) is used to lock the version of Node to the latest LTS.
After installing NVM, run nvm use
. You may need to install the specified version of Node using nvm install
.
The node-gyp package requires a C compiler. If you notice node-gyp errors after installing dependencies, see the instructions for installing a C compiler based on your OS: https://github.com/nodejs/node-gyp#on-macos
yarn install
yarn install
Compile and hot-reload for development.
yarn dev
OR
yarn storybook
The command will output the server URL to visit in your browser, ex. https://localhost:3000.
yarn build
Run Unit Tests with Vitest
yarn test:unit
Run End-to-End Tests with Cypress
yarn build
yarn test:e2e # or `npm run test:e2e:ci` for headless testing
Lint with ESLint
yarn lint
While we have not done a perfect job of applying any of these standards, we recommend the following resources as a starting point for best practices that are observed by this project:
- Writing CSS and HTML: https://codeguide.co/
- Block Element Modifier (BEM) CSS syntax: https://csswizardry.com/2013/01/mindbemding-getting-your-head-round-bem-syntax/
When your feature branch is ready for testing or after you have made any requested changes, you need to run the following command to make sure that the distribution files get updated:
yarn dist
The following is an example of the workflow and not meant to be copied and pasted verbatim. Please review the summary at https://semver.org/ to understand which type of release you should be creating. The version numbers you will use when you are actually going through this process will depend on the current version number and what type of release you are creating.
To see the full options for the command, run npm version --help
.
git checkout 4.x
- Make sure you are on the4.x
branch.git pull
- Make sure you have the most recent updates.npm version patch -m "https://github.com/uiowa/uids/compare/v3.1.0...v3.1.1"
git push
git push --tags
- Go to https://github.com/uiowa/uids/releases/new.
- Enter the "Tag version" using the version with the
v
at the front (e.g. "v3.1.1"). - Enter the "Release title" using the version without the
v
at the front (e.g. "3.1.1"). - Paste in the compare link into the description area:
https://github.com/uiowa/uids/compare/v3.1.0...v3.1.1
- Click the "Publish release" button.
- Profit!
Learn about Fractal components here: https://fractal.build/guide/components/#what-defines-a-component. Note that this project uses Twig (.twig
) instead of Handlebars (.hbs
).
All work on components should be done in the src/components
directory. Each component is contained in its own directory. Some component directories are grouped together for presentation purposes.
If you are starting work on a new component, please make sure that it has status: prototype
in its config file, and it is placed in the src/components/prototypes
directory.
GitHub Actions is used to build and deploy the Fractal artifact to the gh-pages
branch. This branch is set to host UIDS using GitHub Pages. All pushes to a branches or tags will trigger a build.
Branches can be accessed at https://uids.brand.uiowa.edu/branches/{your-branch-name}.