@jtl-software/platform-ui-react

v1.51.2

Published

a day ago

## 🧭 Project Overview

0High
0Medium
0Low

JTL-Platform UI React

🧭 Project Overview

JTL Platform UI React is a modern, accessible UI component library built with React 19, TailwindCSS 4, and Radix UI primitives. It provides reusable components following Atomic Design principles for JTL applications.

Tech Stack

React 19 (peer dependency requirement)
TailwindCSS 4 (used internally; consumers do not need to set it up in their app)
TypeScript 5.6
Vite 6 (build tool)
Vitest 3 (testing)
Storybook 9 (documentation)
react-hook-form + Zod (form validation)
shadcn UI (component reference)
Radix UI primitives

📦 Installation

Install the package using the package manager of your choice:

npm:

npm install @jtl-software/platform-ui-react

yarn:

yarn add @jtl-software/platform-ui-react

pnpm:

pnpm add @jtl-software/platform-ui-react

🔨 Setup

1. Import the Stylesheet

The library ships a pre-compiled stylesheet that includes all the utility classes, design tokens, and a minimal element-level reset its components need. You must import it once at your app entry point.

In JavaScript or TypeScript (most common with Vite, Next.js, CRA):

// In your app entry, e.g. main.tsx, _app.tsx
import '@jtl-software/platform-ui-react/index.css';

Or from CSS:

@import '@jtl-software/platform-ui-react/index.css';

You do not need to configure TailwindCSS in your app to use the library. The required utility classes are already compiled into the shipped CSS.

2. CSS Reset (consumer responsibility)

The library does not ship a full CSS reset. It includes a small targeted reset for form controls (button, input, select, textarea) and replaced elements (img, svg, video) so its own components render correctly, but it does not normalize typography, headings, list bullets, or page-level margins.

If your app does not already have a CSS reset in place, we strongly recommend adding one. Common options:

Full Tailwind preflight (@import 'tailwindcss') if you use Tailwind in your app
normalize.css
tailwindcss-scoped-preflight if you want Tailwind's reset scoped to a specific root

Without a reset, native browser styles (default <h1> margins, list bullets, etc.) will remain in your app, which is usually what you want for content outside the library's components.

3. Styling Variables

The library exposes its design tokens as CSS custom properties. You can use them in your own styles:

Prefer classes like w-[var(--spacing-10)] instead of hard-coded values like w-40.
Override tokens at :root to theme the components (e.g. --base-primary).
For dark mode, set data-color-scheme="dark" on <html> or apply the .dark class to a wrapping element.

🚀 Usage

Basic Component Usage

import { Button, Text, Card } from '@jtl-software/platform-ui-react';

🧩 Component Categories

This library includes the following component categories:

Layout Components

Box, Grid, Stack, Layout, LayoutSection, Card

Form Components

Button, Checkbox, Input, InputOTP, Radio, Select, Textarea, Switch, Toggle, ToggleGroup, FormGroup, Form

Data Display

Text, Badge, Avatar, Table, DataTable, Progress

Navigation

Link, Breadcrumb, Tab, Dropdown

Feedback

Alert, Dialog, AlertDialog, Tooltip, Skeleton

Utility

Icon, Separator, ScrollArea, Collapsible, Popover, Sheet

⚠️ Usage Guidelines

Avoid invalid HTML nesting (e.g., <div> inside <p>, <button> containing <a>).
Do not wrap library components with arbitrary elements unless semantically correct.
Fix any console warnings like Warning: validateDOMNesting(...).

📚 Storybook

The best way to explore all available components and their usage is through Storybook

Running Storybook Locally

After cloning and installing dependencies:

# Install dependencies
pnpm install

# Start Storybook
pnpm storybook

Storybook will be available at: http://localhost:50170

Using Storybook for Documentation

Our Storybook includes:

Component demonstrations with various prop combinations
Interactive controls to experiment with component properties
Documentation on component APIs, props, and examples
Accessibility information
Source code examples

⚡️ Development

Prerequisites

For local development, ensure you are using the Node.js version specified in package.json.
- Mise: run mise install to install the correct versions of node and pnpm
Run pnpm install on repository root to install dependencies

Common Commands

Start Storybook: pnpm storybook
Build the library: pnpm build
Run tests: pnpm test
Run linting: pnpm lint

Import Aliases (Repository Development)

Use internal path aliases for local source imports:

import { Component } from '@/components/component-name';
import { useHook } from '@/hooks';
import { utils } from '@/lib';

🔌 Ports

To prevent conflicts with other services during development, we have a reserved port range for this project: 50170-50179. Please use a port within this range when adding a new service.

| Port | Protocol | Service | | ----- | -------- | --------- | | 50170 | HTTP | Storybook |

📦 Dependencies

This project uses React 19 for both development and as a peer dependency.

"peerDependencies": {
  "react": "^19.0.0",
  "react-dom": "^19.0.0",
}

Projects using this library should use React 19 for optimal compatibility.