ocelot-ui

v0.0.23

Published

24 days ago

Ocelot UI (OUI), a UI framework built with Vue 3 and Tailwind CSS, is designed to be highly performant, optimized, and accessible. It strikes a balance by providing essential features without being overly opinionated, allowing for flexibility in your proj

0High
0Medium
0Low

rickrx

component library vue tailwind

Ocelot UI

Ocelot UI (OUI), a UI framework built with Vue 3 and Tailwind CSS, is designed to be highly performant, optimized, and accessible. It strikes a balance by providing essential features without being overly opinionated, allowing for flexibility in your projects.

Head to OcelotUI on Netlify for the Storybook site — this auto-publishes on every PR merge.

OcelotUi-anim

Installation

npm install ocelot-ui

Prerequisites: Vue 3.5+, Tailwind CSS v4, Node.js 20+

Optional feature dependencies:

# Table
npm install @tanstack/vue-table

# LightboxImage
npm install photoswipe

# Video
npm install plyr

# QrCode
npm install qrcode

Install only the packages for the components you actually use. OUI will warn in development if Table, LightboxImage, Video, or QrCode is mounted without its matching dependency.

For example:

Table requires @tanstack/vue-table
LightboxImage requires photoswipe
Video requires plyr
QrCode requires qrcode

1. Configure Tailwind

Import the OUI Tailwind plugin alongside your Tailwind import. This tells Tailwind to scan OUI components so their utility classes are included in your build:

/* your main CSS file */
@import "tailwindcss";
@import "ocelot-ui/tailwind.css";
@custom-variant dark (&:where(.dark, .dark *));

2. Import the stylesheet

// main.js / main.ts
import 'ocelot-ui/style.css'

The stylesheet (ocelot-ui/style.css) contains Vue transition styles.

3. Import components

Use named imports directly in your components:

import { Button, Dialog, Sidebar } from 'ocelot-ui'

4. Portal targets

Dialog, Toast, and CommandPalette use Vue Teleport. OUI creates #portal-target automatically after mount when it is missing, or you can provide one yourself in index.html.

Table notes

Table includes a built-in settings menu for density, column visibility, and pinning. On small screens it can either stay horizontally scrollable or switch rows into stacked cards with mobileLayout="card".

CommandPalette notes

CommandPalette also teleports to #portal-target. Register commands with useCommandPalette(), then mount the component once near the app root so it can respond to Ctrl+K / Cmd+K.

NavigationBar notes

NavigationBar includes desktop nav slots, two-level submenu support, and a #mobile-menu slot for small-screen navigation. Use mobileMenuOpen / update:mobileMenuOpen when the host app needs controlled state.

Forms and RTL

Storybook includes guidance for form validation integration and RTL support. OUI provides accessible form structure but leaves validation rules, touched/submission state, async checks, and server error mapping to the host app or its chosen validation library. Vee-Validate, Zod, native HTML constraints, and server-driven validation should all feed the same FormField error contract.

Dark mode

Toggle dark mode via the .dark class on <html>:

<html class="dark">...</html>

All components and product pattern stories should be checked under the Storybook dark theme before release. New component stories should use semantic Tailwind colours with dark: variants for any text, border, or background colour they introduce.

Bundle analysis

To inspect the library bundle composition locally, run:

npm run build:analyse

This generates a treemap report at dist/bundle-analysis.html.

Publishing to npm

To publish a new version:

Ensure you are on main and up to date
Run npm run publish:npm
Select a bump type when prompted: patch, minor, or major
The script will bump the version, commit, tag, push to GitHub, and publish to npm

Netlify

OcelotUI's Storybook is hosted on Netlify at https://ocelotui.netlify.app. PRs automatically deploy on merge to main.