README.md

juvo

Balanced design system built around the Harmony color palette

Principles

/ˈju.vo/ means to assist, serve and delight. Key characteristics of this project are:

• WCAG 2.2 compliance
• React Server Components support
• React Hook Form integration via ref prop for controls
• Single container element for top-level UI components, allowing className to be prepended
• Utility-first CSS with Tailwind

See also inspirations for more.

Usage

Firstly, install the package:

pnpm add juvo

Once the accompanying styles are loaded as shown below, components can be imported and used like:

import { ButtonPrimary } from "juvo";

export default function App() {
  return <ButtonPrimary>Click me</ButtonPrimary>;
}

If using TypeScript, consider adopting @total-typescript/tsconfig. Package entry points may fail to resolve otherwise.

Standalone

Import styles from your app’s root:

import "juvo/styles/standalone.css";

With Tailwind CSS (recommended)

1. Add build-time dependencies:

   pnpm add -D tailwindcss postcss postcss-preset-env

2. Set up .postcssrc.json in your project root, making sure to disable all logical properties and values plugins:

   {
     "plugins": {
       "tailwindcss/nesting": "postcss-nesting",
       "tailwindcss": {},
       "postcss-preset-env": {
         "features": {
           "nesting-rules": false,
           "float-clear-logical-values": false,
           "logical-overflow": false,
           "logical-overscroll-behavior": false,
           "logical-properties-and-values": false,
           "logical-resize": false,
           "logical-viewport-units": false
         }
       }
     }
   }

   • Extensive browser support is provided via Browserslist
   • The official CSS Nesting syntax is used over the Sass-like one

3. Configure tailwind.config.js in your project root, amending content as per Tailwind’s framework guides:

   import * as path from "node:path";
   
   import juvoPreset from "juvo/tailwind-preset";
   
   /** @type {import("tailwindcss").Config} */
   export default {
     content: [
       "./src/**/*.{js,jsx,ts,tsx,mdx}",
       path.join(path.dirname(require.resolve("juvo")), "**/*.js"),
     ],
     presets: [juvoPreset],
   };

   • Theme-dependent color tokens are exposed under the ui- prefix
     • To switch between color themes, apply .theme-dark and .theme-light classes as-is or through the @apply directive:

       @media (prefers-color-scheme: dark) {
         html {
           @apply theme-dark;
         }
       }

   • Transition timings are set to the ease-out function of Tailwind by default

4. Add src/styles.css and import it from your app’s root:

   @import "tailwindcss/base";
   @import "juvo/styles/base.css";
   
   @import "tailwindcss/components";
   
   @import "tailwindcss/utilities";

Inspirations

Philosophy

• The “everything bagel” of components — Dani Guardiola
• Reach UI Philosophy — Ryan Florence
• Margin considered harmful — Max Stoiber
• Contextual defaults — Mark Dalgleish
• Everything You Know About Web Design Just Changed — Jen Simmons

Guidelines

• Web Interface Guidelines — Rauno Freiberg
• Expressive React Component APIs with Discriminated Unions — Andrew Branch

Accessibility

• HTML: The Inaccessible Parts — Dave Rupert
• Using CSS to Enforce Accessibility — Adrian Roselli
• HTML Accessibility Blog — Steve Faulkner
• Accessiblity Support — Michael Fairchild

Design

• Material Design — Google
• Visual design rules you can safely follow every time — Anthony Hobday
• Choosing the correct default easing for Popmotion — Matt Perry
• Practical UI — Adham Dannaway

Examples

• The Component Gallery — Iain Bean
• UI Playbook — Rauno Freiberg
• UI & UX Design Tips — Jim Raptis

Contributing

Please refer to the contribution guidelines for details.