USWDS-Vue

Vue 3 support is coming!!!

Working on this right now, I hope to get this out by the March 1st!

Introduction

Vue USWDS component library

This is a front end component library whose aim is to develop Vue.js implementations of the design patterns defined by the United States Web Design System (USWDS).

The primary goal of this library is to document and provide common UI components that can be included in other projects that adhere to or are based off of the USWDS, removing a significant amount of overhead UI development from such projects.

Documentation

Full docs can be found here

A Bootstrap Theme for UWSWDS

Rather than use USWDS as-is, the philopshy of this library is to create a bootstrap theme for USWDS and then build components on top of that. Thus leveraging the immense amount of work that has gone into making Bootstrap work on every platform, everywhere. Not to mention it's 508 compliance.

This approach is in full compliance of the 21st Century IDEA act. Indeed, combining the best-of-breed private sector technology such as bootstrap with the domain-specific design work of the USWDS team gives the best of both worlds - and is exactly what the 21st Century IDEA act was trying to achieve.

Getting Help & Contributing

If you need help, submit an issue or you can find me on Twitter at @MikeJPritchard. Please just DM me to let me know you're using this. If I know people are using this, then I'll be more active building and supporting it!

And even better, if you want to contribute let me know!

Install

# With yarn
yarn add uswds-vue bootstrap

# With npm
npm i uswds-vue bootstrap

You can import globally;

// Import bootstrap, or import in your head for SSR builds
import 'bootstrap'

// And then import the vue component library
import { UswdsVue } from 'uswds-vue';
Vue.use(UswdsVue);

// Or import individual components, e.g.;
import { UsCard } from 'uswds-vue';
Vue.use(UsCard);

You will also need to import the USWDS styles;

<link rel="stylesheet" href="~uswds/dist/css/uswds.min.css">
<link rel="stylesheet" href="~uswds/dist/css/uswds-vue.min.css">

Or in your css files;

@import "~uswds/dist/css/uswds.min.css";
@import "~uswds-vue/dist/uswds-vue.css";

Or in your sass files;

@import "~uswds/dist/css/uswds.css";
@import "~uswds-vue/src/styles/uswds-vue.scss";

Building & Contributing

To get started locally just run yarn install, you can develop components in your own projects by pulling in the local copy of usdws-vue (using yarn link or just manually import).

Personally, I find it easiest to develop both the component and the docs at the same time. VuePress has hot reloading, so you can develop the component and also create the docs at the same time. You can spin up the VuePress locally by running yarn docs:dev.

Documentation

The project uses VuePress, all the docs are found under /src-docs/guide. It's fairly easy to add a new component;

Create a new page by adding an entry to the side-nav, this is done by editing themeConfig.sidebar in /src-docs/.vuepress/config.js. The entry you add is the file path to the markdown doc itself.

For example, you can see the documentation for the alert component is in the children array in the object with a title Component in themeConfig.sidebar. The entry is components/alert, which corresponds to the markdown file in the directory /src-docs/guide/components/alert.md.

Contributing & Versioning

We follow the semantic versioning convention, when you commit do so in the following manner;

git commit -m "fix: JIRA-1234 Fixed bug on foo"
git commit -m "feat: JIRA-2345 Adds new Widget"
git commit -m "chore: JIRA-3456 Updated README"
git commit -m 'feat: JIRA-4567 Added new theme

We use standard_version to automate versioning and release notes.

Simply run yarn run release to bump the version number appropriately and generate release notes. Run git push --follow-tags origin master to publish.