UI Design System (UIDS)

A design system for the University of Iowa.

See the documentation at http://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. http://localhost:3000.

yarn build

yarn test:unit

yarn build
yarn test:e2e # or `npm run test:e2e:ci` for headless testing

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/

Before opening or updating a PR, run:

yarn build

yarn build generates and validates token CSS when src/tokens/** changes; no generated token files are committed.

Releases use Semantic Versioning. The release workflow builds the tagged source and attaches an installable package to the GitHub release. Do not run npm pack or upload the tarball manually.

package.json and the top section of CHANGELOG.md always name the next release. After each release, the first PR with a changelog entry opens a section for the next version and bumps package.json to match. SemVer prerelease versions such as 5.0.0-alpha.1 are valid.

1. Create a GitHub release from the latest commit on 5.x. Tag it with the package.json version prefixed with v, so version 5.0.0-alpha.1 gets tag v5.0.0-alpha.1.
2. Publish the GitHub release. The Release workflow verifies the tag/version match, runs yarn build, creates uids-<version>.tgz, and attaches it to the release.
3. Wait for the workflow to finish and verify that the tarball appears in the release's assets before asking a consumer to update. If it fails, rerun the Release workflow with that tag; do not upload a replacement tarball manually.

Consumers install the release artifact by URL:

"@uiowa/uids": "https://github.com/uiowa/uids/releases/download/v5.0.0/uids-5.0.0.tgz"

uids/uids.css is the full stylesheet. When loading individual component stylesheets, load uids/uids-core.css once for tokens, fonts, reset, base styles, and layout foundations:

import 'uids/uids-core.css';
import 'uids/components/button.css';

Use uids/tokens.css when only the token custom properties are needed.

Components are Vue 3 components documented with Storybook. Each component directory contains its .vue file, its .stories.js file, and an index.ts.

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.

GitHub Actions is used to build and deploy the Storybook site 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 http://uids.brand.uiowa.edu/branches/{your-branch-name}.