Pimp is a components library that contains a set of polished Vue components.
Website | Documentation
---
## Pimp mission
Pimp aims to bring order and consistency to all of our products and processes. We elevate user experience and increase the speed and efficiency of how we design and build products.
## Installation
`pimp` components are served as an [npm package](https://www.npmjs.com/package/@citizenplane/pimp).
Add them to your project by running:
```bash
// with npm
npm install @citizenplane/pimp
// with yarn
yarn add @citizenplane/pimp
```
## Usage
### In a nuxt project
1. Add this line to your `nuxt-config.js`:
```javascript
// nuxt-config.js
...
css: [
{ src: '@citizenplane/pimp/dist/pimp.css' },
],
...
```
2. Include any of our components in your project and use it:
```vue
```
If you want to use any component without having to import them manually, you can create a plugin:
1. Create a plugin called `citizenplane-pimp.js`:
```javascript
// ~/plugins/citizenplane-pimp.js
import Vue from 'vue'
import Pimp from '@citizenplane/pimp'
Vue.use(Pimp)
```
2. Add this line to your `nuxt-config.js`:
```javascript
// nuxt-config.js
...
plugins: [
{ src: '~plugins/citizenplane-pimp.js' },
]
...
```
3. Use components directly in your project without having to import nor declaring them:
```vue
```
## Components
Now that you're all set up, you can retrieve components documentation on [pimp.citizenplane.com](https://pimp.citizenplane.com).
## Reduced motion
Under `prefers-reduced-motion: reduce`, pimp's shipped CSS flattens every transition's duration to near-zero and every animation's duration/iteration-count to a single near-instant pass β including your app's own transitions and animations, not just pimp's. Only an element entering or leaving (a Vue ``'s `-enter-active`/`-leave-active` classes) keeps a short, real opacity fade; everything else, including plain opacity/color hover transitions, becomes instant. This is a behaviour change apps should be aware of if they rely on their own transition timing.
Mark an animation that conveys real state (e.g. a loading spinner) as exempt with `data-motion="essential"` on the element or an ancestor β its `animation-*` timing is left untouched.
In script, `useReducedMotion` (exported from `@citizenplane/pimp`) reflects the OS preference reactively, for JS-driven cases CSS can't express.
## π§βπ» Contributing to Pimp
We are working on making this project a fully open source. We appreciate any contributions you might make.
### π΄ Step 1. Fork this repository
In order to contribute to Pimp, you need to fork this repo, and develop on your own local clone.
If you don't know how to do so, follow this [guide](https://help.github.com/en/github/getting-started-with-github/fork-a-repo)!
### π Step 2. Get playground up and running
First, move into your local cloned repository with the help of `cd`, after that install your `node_modules` with:
```bash
// with npm
npm install
```
To actually start seeing the components you have to run the project with the command:
```bash
npm run dev
```
Now go to `http://localhost:8080` in your browser.
### π Step 3. Make your changes
Now you can start developing!
All the components are under the `src/components/` directory and associated code changes will automatically be reflected in the playground.
In order to run the documentation page locally, run these commands in your terminal:
```bash
cd docs
npm install
npm run dev
```
Now you can visit `http://localhost:8080/` in your browser.
### π Step 5. Before pushing
Run the checks used in CI:
```bash
npm run lint
npm run types
```
### π Commit Guidelines
This project follows [Conventional Commits](https://www.conventionalcommits.org/) specification. All commit messages are automatically validated.
#### Using Interactive Commit Tool
For an interactive commit experience that guides you through creating a proper commit message:
```bash
git add .
npm run commit or git cz
```
#### Manual Commit Format
If you prefer to write commit messages manually, follow this format:
```
:
```
**Available types:**
- `feat`: A new feature
- `fix`: A bug fix
- `docs`: Documentation changes
- `style`: Code style changes (formatting, etc.)
- `refactor`: Code refactoring
- `perf`: Performance improvements
- `test`: Adding or updating tests
- `chore`: Maintenance tasks
- `ci`: CI/CD changes
- `build`: Build system changes
- `revert`: Revert a previous commit
**Rules:**
- Keep the description under 48 characters
- Use lowercase for the description
- Don't end with a period
**Examples:**
```bash
git commit -m "feat: add new button component"
git commit -m "fix: resolve input validation issue"
git commit -m "docs: update installation guide"
```
The commit message will be automatically validated before the commit is accepted.
### π Step 6. Making your pull request
To be done
### π₯ Step 7. Pat yourself on the back
Congrats, you're officially a Pimp contributor!
## Feedback
We want to provide only components of the highest quality. We canβt do that without your feedback. If you have any suggestions about what we can do to improve components, please report it directly as an issue or drop us a line at tech@citizenplane.com.
## π Respect earns Respect
Please respect our Code of Conduct, in short:
- Using welcoming and inclusive language
- Being respectful of differing viewpoints and experiences
- Gracefully accepting constructive criticism
- Focusing on what is best for the community
- Showing empathy towards other community members
## License
Pimp is released under the MIT license.
Copyright Β© 2021 CitizenPlane, Inc.
