Pdap-design-system NPM

PDAP Design System

A Vue component library, styling system, and image asset repository for PDAP-branded client apps.

Coverage Badge

Usage

Install the package

npm install pdap-design-system

Import the stylesheet in the app's entrypoint (usually index.js or main.js, at the root of your project)

// index.js | main.js

import 'pdap-design-system/styles';

Import and use the components

import { Button, Form } from 'pdap-design-system';

Extend the es-lint config, for consistency in linting between client apps: First npm install --save-dev @pdap-design-system/eslint-config, then, in eslintrc:

{ 
  ...,
	extends: [
		"@pdap-design-system/eslint-config",
    ...
	],
}

(Optional) Import the tailwind config if you need to use additional tailwind styles.

// tailwind.config.js
import { tailwindConfig } from 'pdap-design-system';

/** @type {import('tailwindcss').Config} */
module.exports = {
  // Spread base config
  ...tailwindConfig,
  // Then override with `content` property and any other superseding config (if necessary - it really shouldn't be)
  content: [
    "./index.html",
    "./src/**/*.{vue,js,css}",
  ],
}

If the project is using TypeScript, the component props definitions and other types are exposed for import as well.
n.b. This can be particularly useful for composing Form schemas, where Input schema objects are defined differently depending on the type of input desired.

import { PdapInputTypes } from 'pdap-design-system';

See the component documentation for details on each component's API.

About images

PDAP image assets contained in this repo are built to the /dist directory. For convenience an importing alias /images has been added.

import 'pdap-design-system/images/acronym.svg';

Or, if you need them all, you can import all images at the app level. Just remember that if it's imported it gets bundled with your production app, so take care not to import unneeded images.

import `pdap-design-system/images`;

Development Setup

Clone the repo

gh repo clone Police-Data-Accessibility-Project/design-system

CD into the project directory and install dependencies

cd design-system
npm i

Step 2 should result in the build script being run after packages are installed. Check the dist directory for changes. You then may want to take one or both of the following steps:

If build wasn't called when you installed deps, build styles and images to the dist directory:

npm run build

To watch for changes and update the build as you make changes:

npm run build:watch

If you use VS Code as your editor, you may want to install the tailwind VS Code extension, which helps with intellisense and the custom at-rules used by TailwindCSS.
Read the contributing guide for development requirements and tips.

Assets

Use these brand assets. Use this terminology.

Scripts reference

Script	What it does
`_commit`	Create conventional commits
`build`	Builds the library
`build:watch`	Builds the library and watches for file changes
`ci`	Remove all generated files and re-installs deps
`clean`	Remove all generated files (except `package-lock.json`)
`clean:deps`	Remove node_modules directory
`clean:build`	Remove dist directory
`clean:test`	Remove testing coverage reports
`lint`	Lint everything
`lint:es`	Lint `ts` and `vue` with `eslint`
`lint:css`	Lint `css` and `vue` with `stylelint`
`lint:ts`	Lint `ts` with `tsc`
`test`	Run all test suites
`test:changed`	Run only test suites affected by changed files
`typecheck`	Run type check on all `ts` and `vue` files

n.b. There are some other scripts defined in the package.json "scripts" field, but they are mostly for CI or cleanup post-build, etc. You shouldn't need them.

Releasing

Incremental updates can be added to main directly via a PR. For more significant updates, the beta branch can be used for releasing incremental beta releases to test the bigger feature without releasing to production.