@cyril2day2/pristine-ui

v1.0.3

Published

6 days ago

A collection of reusable, clean‑design Vue 3 UI components

0High
0Medium
0Low

cyril2day2

vue ui components design-system

Pristine UI

npm version license

A collection of reusable, clean‑design Vue 3 UI components built with TypeScript and Sass. Designed for developers who value clean design, accessibility, and a straightforward developer experience.

Features

Vue 3 – Composition API and <script setup> syntax
TypeScript – Fully typed components and utilities
Design Tokens – Consistent spacing, colors, typography via CSS custom properties
Clean design – Subtle shadows, rounded corners, familiar interactions
Accessible – WAI ARIA attributes, keyboard navigation, focus management
Tree‑shakeable – ES module exports with side‑effect‑free JavaScript
CSS‑variable based theming – Light/dark theme support via CSS custom properties

Components

CardDisplay – Outlined and elevated card containers
CheckBox – Clean checkbox with tri‑state (checked/unchecked/indeterminate)
ComboBox – Filterable dropdown with keyboard navigation
PushButton – Button with role variants (normal, primary, destructive, cancel)
SegmentedControl – Capsule or rounded‑rectangle segmented control
SwitchToggle – Clean toggle switch with smooth animation
TextArea – Resizable textarea with character counter
TextField – Clean text field with clearable support

Installation

npm install @cyril2day2/pristine-ui
# or
pnpm add @cyril2day2/pristine-ui
# or
yarn add @cyril2day2/pristine-ui

Peer Dependencies

Pristine UI expects vue (^3.5.26), normalize.css (^8.0.1) and pristine‑styles (^0.1.0) to be installed in your project. If you haven’t added them yet:

npm install vue normalize.css pristine-styles

Note: pristine‑styles already includes normalize.css as a dependency, so installing pristine‑styles will automatically satisfy the normalize.css requirement. However, listing both keeps the dependency explicit.

Usage

Import Individual Components (Recommended)

<script setup lang="ts">
import { PushButton, SwitchToggle } from '@cyril2day2/pristine-ui'
</script>

<template>
  <PushButton role="primary">Click me</PushButton>
  <SwitchToggle v-model="enabled" />
</template>

Use the Plugin for Global Registration

import { createApp } from 'vue'
import App from './App.vue'
import PristineUI from '@cyril2day2/pristine-ui'

const app = createApp(App)
app.use(PristineUI)
app.mount('#app')

After registering the plugin, all components become available globally without explicit imports.

Include Default Styles

Components rely on CSS custom properties (design tokens) for colors, spacing, etc. The design tokens are required—without them, components will have virtually no styling (colors, spacing, typography, etc.). To get the expected appearance, you must import both the component styles and the design tokens.

Install the design tokens package (if you haven’t already):
```
npm install pristine-styles
```
Import the design tokens in your main CSS/SCSS file:
```
@import 'pristine-styles';
```
or in SCSS:
```
@use 'pristine-styles';
```

Import the component styles from the library:

import '@cyril2day2/pristine-ui/dist/style.css';

If you wish to customize the design tokens, you can override any CSS custom property after importing pristine‑styles. For advanced customization, you may replace pristine‑styles entirely with your own token system, provided you define the same set of CSS custom properties.

Theming

Pristine UI supports light/dark themes via CSS custom properties. The token file (provided by the pristine‑styles package) includes automatic theme detection via prefers-color-scheme and a manual .dark class toggle.

Using OS Preference

No extra work needed—the token CSS automatically adapts to the user’s system preference.

Manual Theme Toggle

Add a .dark class to the <html> element to switch to dark theme:

document.documentElement.classList.add('dark')

Remove the class to revert to light theme.

Customizing Tokens

Override any token by re‑defining the corresponding CSS custom property in your own stylesheet:

:root {
  --color-blue: #0a84ff;
  --space-4: 1rem;
  /* … */
}

Styling Approach

Pristine UI separates component styles (layout, component‑specific CSS) from design tokens (colors, spacing, typography, etc.). This separation gives you full control over the visual design while keeping the component logic independent.

Component styles are bundled in @cyril2day2/pristine-ui/dist/style.css. They define how components are laid out and interact, but they reference design tokens for all color, spacing, and typography values.
Design tokens are provided by the pristine‑styles package. They are a set of CSS custom properties (variables) that you can override in your own stylesheet.

To customize the appearance, simply re‑define any token in your CSS:

:root {
  --color-blue: #0a84ff;
  --space-4: 1rem;
  /* … override any token defined in pristine‑styles */
}

Because tokens are decoupled, you can even replace pristine‑styles entirely with your own token system, as long as you define the same set of CSS custom properties.

Component API

Each component is documented with TypeScript interfaces. Hover over the component name in your IDE to see available props, events, and slots.

For a live interactive demo, run the local development server (see Development below).

Development

This repository includes a demo page that showcases all components. To run it locally:

Clone the repository
Install dependencies:
```
pnpm install
```
Start the development server:
```
pnpm dev
```
Open http://localhost:5173 in your browser.

Running Tests

Unit tests are written with Vitest and Vue Test Utils.

pnpm test:unit

Linting

pnpm lint

License

MIT © psi

Acknowledgments

Design inspired by Apple’s Human Interface Guidelines
Built with Vite and Vue 3
Functional utilities powered by Underscore.js

Contributing

Contributions are welcome! Please open an issue or a pull request on GitHub.

Maintainer: psi – cyril2day – [email protected]