police-data-accessibility-project / design-system

Vue component library and assets for PDAP-branded client apps

PDAP Design System

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

Usage

1. Install the package

npm install pdap-design-system

1. 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';

1. Import and use the components

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

1. 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",
    ...
    ],
}

1. (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}",
  ],
}

1. 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';

1. 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

1. Clone the repo

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

1. CD into the project directory and install dependencies

cd design-system
npm i

1. 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:

2. 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

1. 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.

2. 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
dev	Run demo app to check visual changes to components
docs	Run script to automatically aggregate links to component README 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.

design-system's Issues

semantic colors & typography

there are fancier ways to do colors than specifying hex codes: we can use variables, plus options for tints and shades.

there are fancier ways to do typography than specifying font sizes: we can use variables, and rems.

this is part of #9

reference our brand assets

Update checkbox input to be viable

As a part of the search v2 work, the designs call for two styles of checkbox.

• Update checkbox input to properly handle change and input events.
• Ensure checkbox input works as expected with form
• Write tests to cover it
• Update documentation
• Raise PR against beta

data-sources-app components → design system

Context

We have some components stacking up in our app. Let's abstract these into reusable components in the design system, ideally using Tailwind!

Requirements

This is a refactor, so things should work the same but details of appearance may change.

Docs

If any best practices can be derived here for future front end developers, we should make changes to our internal docs or CONTRIBUTING.md or something. We can discuss this.

Open questions

consider: should new css go in global.css or a use a component-level custom CSS file?

• for broadly used, lightly styled components, like containers, use global-styles.css
• for broadly used, uniquely styled components, like buttons, scope styles to the component.
• for uniquely used, uniquely styled things like a map, scope styles to the component.
• Export Vue.js component library, or simply create the component styles here and reference the classes in the vue files elsewhere?

`preview` command failing locally for `QuickSearchForm` on `pdap.io`

The QuickSearchForm submit method is failing locally when I run build and preview (not with regular dev server). I think I understand why from the console output, and can raise follow-up PRs to design-system and pdap.io to fix.

^ See point 1 in this comment.

Screen.Recording.2024-01-08.at.2.12.09.PM.mov

Also let's check data-sources and make sure that we're not running into the same issue there.

tailwind usage/distribution/flexibility

Currently

As part of distributing the pdap-design-system package, we're using and compiling tailwindcss. This gives us upstream control over the components, but less downstream flexibility. To prevent people from making custom classes, we should recommend that they install tailwind on any downstream projects for which they would like to make custom classes.

It seems like we're gonna stick with this, so we should set people up for success:

• document the tailwind configuration (linking to the config would be OK) so that people better know how to use it.
• make sure people know to symlink (in CONTRIBUTING.md guide of this repo, maybe move it to README) so they can easily test updates to the design system locally
• make sure usage guide includes best practices for custom css, new components, and updates to the design system

use tailwind ui

https://tailwindui.com/
https://tailwindui.com/documentation

Context

Our first Vue app is in progress. We'd like to keep all our microservices in visual alignment.

Tailwind is opinionated about utilities-based classes, and HTML that is dependent on CSS. Using it will prevent our CSS from growing, and make it maintainable.

This will likely require reworking the existing grid, forms, and buttons.

Next, we should prioritize components which apply to the views in our roadmap.

Requirements

• Release a new npm version of the design system which uses tailwind UI (requires tailwind css)
• Things should look more or less the same, unless there are tweaks for accessibility
  • may want to replace our existing grid and responsive layout with tailwind's
  • may want to replace other declared styles with tailwind's
• Don't worry too much about the main website—we can keep that on the current version of the design system because it's an npm package.
  • that said, if it's easy enough to bring our static site along, we should do it (can be done separately/later)
• #4 (can be done separately/later)

Docs

• Update this repo's README and CONTRIBUTING with any requirements changes or contributing considerations the front end.
• We may want deeper docs somewhere

Create dropdown component

As a part of the search v2 work, we will need a dropdown for search filtering

• Create a dropdown
• Ensure it is accessible
  • Use appropriate aria attributes
• Write tests to cover
• Update documentation
• Raise PR against beta

Move ErrorBoundary component from data-sources -> design-system

We defined ErrorBoundary in data-sources. This should be moved over to design-system.

• Move ErrorBoundary to src/components
• Write tests to cover it

Replace `FlexContainer` and `GridContainer` with utility classes.

• Extract styling from FlexContainer, GridContainer, and GridItem
• Define classes in the @components layer.
• Replace all instances in the repo with these class names
• Mark FlexContainer, GridContainer, and GridItem as deprecated using a TSDoc comment. (We will remove once these are all stripped from current usage in other apps.
• Update documentation

Create Breadcrumbs component

Component should

• Render all matching routes, with links to "ancestor" routes and paragraph display for current route.
• Use a breadcrumbText property on route.meta for the display text, falling back to the route name otherwise.
• Be covered by tests
• Be covered by updated documentation

Add accessibility linting

• Add eslint-plugin-vuejs-accessibility to the eslint config
• Adjust the configuration settings
• Fix any a11y issues raised by the plugin
• Update documentation

This blog post is a good overview of how to implement.

design system checklist

Lot of stuff we could include that didn't seem like a must-have at the start:

https://www.designsystemchecklist.com/

inaccessible gold colors

our brand gold #d5a23c doesn't pass accessibility guidelines, at about 2.32 contrast. We use it for every link and button.

This issue

• bandaid: darken the gold

Future work

• consider updating the colors so that wine is the primary CTA color, and warm or wine neutral is used throughout

Miscellaneous updates and simplifications

• Remove CLI. It is no longer necessary as all consuming applications are using Vue
• Create build and coverage badge workflows.
• Delete current node scripts that create badges
• Update recommended extensions to remove deprecated ext.

Update styling to match search v2 updates

As a part of the search v2 work, the styling is changing.

• Update layout of components
• Update borders and other incidental values of components
• Raise PR against beta.

Create loading spinner / shimmer

As a part of the search v2 work, we want both a loading spinner and a shimmer effect

• Create a loading spinner component (use an SVG)
• Create a shimmer component (just a div with animation classes applied)
• Write tests to cover new components
• Update documentation
• Raise PR against beta

Update to public sans

https://fonts.google.com/specimen/Public+Sans/about
https://github.com/uswds/public-sans

We're currently using Franklin—this is a nice open-source iteration. Feature-packed!

Franklin is still a gorgeous, historic font for print; if we ever print anything, we can use it.

Button component styles are overridden by user agent in some browsers

When type="submit" is added to one of our Button components, user agent styles override our background styles with a transparent in Firefox and Chrome.

2023 launch visual refinements

• quick search page
• results page
  • placeholder text cut off
  • centered containers
• left-aligned text
• switching between active nav items causes them to move around (switch to outline instead of border?)

Preserve input values on custom form errors

See the password reset / signup routes in data-sources. When passwords are mismatched, the form values clear. They should be preserved, so that the user does not need to re-type values they know are correct.

Update release workflow to include a beta release strategy

As a part of the search v2 work, there will be a lot of updates to this repo. We would like to release frequently to test these updates without disturbing the main branch or production release flow.

• Create beta branch in git
• Modify release workflow and semantic-release config to support this.
• Test by releasing a "beta" release that matches the current prod release

Form and Input: refactor, create test to cover

In order to get the initial component library work completed, we stopped short of writing the test for Form and associated components.

See other components for examples of tests.

Initialize design system

https://www.designsystemchecklist.com/

• CSS setup
  • global CSS to start, component-level things can come later
  • utility classes, organized
  • responsive styles, organized
  • merge duplicate selectors
• HTML components
  • buttons
  • navigation
  • code line and block font style
  • anything from /pdap.io
• documentation of purpose and principles
• getting started guide for integration
• consider using storybook

Update SVG handling

Currently we are using string and source values. This make svg handling relatively inflexible.

• Explore options for componentizing SVGs so that clients have an easier time using.
• Maintain export of images for backwards compat

Update `Form` to include validators for `email` and `password`

This issue is to add support for Vuelidate form validators in the PDAP Form component, to accommodate Form's usage with user authentication.

• Add support for password input to PdapInput
• Add an email validator.
• Add a password validator that requires basic security (one capital letter, one lowercase, etc.)

Create demo page to inspect components

Export eslint config for use in other client apps

Follow the pattern established the /config directory, from which we currently export the TailwindCSS config.

The design-system config itself is designed for typescript, so this will be a two-part project.

• Create an eslint-config directory and create a sub-package @pdap-design-system/eslint-config.
• Export the base config from this package. This will bundle the config as a part of the package, for use in other projects.
• In the root directory, update eslintrc.json -> eslintrc.cjs and extend the base config from @pdap-design-system/eslint-config.
• Update the README to ensure ease of use.

Remove deprecated components

Remove FlexContainer, GridContainer, and GridItem components.

QuickSearchForm component

Create re-usable QuickSearchForm component.

• Create new component QuickSearchForm
• Form with schema for two inputs, named location and searchTerm
• On search, redirect to {app-url}/search/searchTerm/location.

Notes

1. There is an example Form here
2. This blocks Police-Data-Accessibility-Project/pdap.io#146
3. This blocks Police-Data-Accessibility-Project/data-sources-app#92

Add `"tertiary"` `intent` value for `Button`

This will allow for buttons to be used without styling (i.e. for the DataSourcesStaticVew component in data-sources

CI/CD Pipeline - Initial

Context

To that point, we probably want to protect npm publish with an access token or (even better) implement a workflow in GH actions to publish automatically on merges to main when certain conditions are met, and gate npm publish behind a token so it can't be used outside of GH. Otherwise, anybody with access to the repo can just publish a new version whenever.

Originally posted by @joshuagraber in #10 (comment)

Requirements

• Add github actions to gate PRs by build, lint, and test scripts.
• Add lint-staged library and configure to lint staged files on commit, using husky library to perform actions on commit hooks.
• Add commitizen library and configure to enforce semantic commit messages.
• Add semantic-release library and add github action to publish automatically on merges to main.
• Ensure semantic-release is configured to automatically update package.json, README.md, and CHANGELOG.md

Docs

• make sure the CONTRIBUTING guide reflects this

Consider

• Should we just use GitHub Releases at this point?

CI/CD pipeline

• Add github actions to gate PRs by build, lint, and test scripts.
• Add lint-staged library and configure to lint staged files on commit, using husky library to perform actions on commit hooks.
• Add commitizen library and configure to enforce semantic commit messages.
• Add semantic-release library and add github action to publish automatically on merges to main.
• Ensure semantic-release is configured to automatically update package.json, README.md, and CHANGELOG.md

Graceful 404s & error boundaries

Context

We should maybe add an issue to handle 404s gracefully in the site with a default route and an error boundary or two.

Might also want to think architecturally about how we want to handle UI error/status messages generally. Do we want a toast component or popup? Or should we add an error message slot to the form components so that forms handle request status? Lots of good options, but when we sync on the roadmap, that may be something to discuss.

• @joshuagraber

Requirements

• Establish a global error handling strategy that includes capturing, logging, and displaying errors gracefully.
  • forms: we should tell people what's up with their form, if it's incorrect
  • search: we should use a persistent error message clarify why there are sometimes 0 matching results (if the search failed somehow vs. there are actually 0 results and they should request data)
• Develop a generic 404 view component that can serve as an error boundary.
  • I would prefer we not get too cute with error messages—we should be as informative as possible (including "we don't know what went wrong") and not funny about how a bunch of kittens are playing in our wires like yarn. or whatever

Docs

• Document the integration process for the error handling components, ensuring it's adaptable for future microservices.

move pdap.io classes to a custom stylesheet

There are a few things that are really just for the website.

Update QuickSearchForm validation

Per comments on this issue, the QuickSearchForm should only complete routing if 1 of the form values exists. The other, empty, value, should be set to 'all'.

Currently, users can submit the form without entering any values.

Miscellaneous documentation updates

One file to rule the component docs is getting clunky.

Let's:

• Split doc/components.md into individual markdown files per component
• Add some TSDoc comments to components so that we get some intellisense when using components
• Note: See the deprecation comments in FlexContainer and GridContainer for an example.
• Add script to aggregate component README files