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 (required peer dependency)
• 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. TailwindCSS Configuration

This library requires TailwindCSS 4. If you haven't set up TailwindCSS in your project yet, follow the official Tailwind CSS installation guide.

2. Import Styles

In your main CSS file (e.g., globals.css or index.css), import the library styles:

@import '@jtl-software/platform-ui-react/dist/main.css';
@import 'tailwindcss';
@source 'node_modules/@jtl-software/platform-ui-react/dist';

3. Styling Variables

• Always use CSS variables from src/styles for spacing, colors, and sizing.
• Prefer classes like w-[var(--spacing-10)] instead of hard-coded values like w-40.
• Avoid arbitrary hard-coded values in Tailwind utility classes.

🚀 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.