@versini/ui-system

!npm package minimized gzipped size>)

> Layout and system components for React applications built with TypeScript and TailwindCSS.

The System package provides foundational layout components including flexbox grids, theme providers, and other system-level utilities for building consistent user interfaces.

Table of Contents

- Features
- Installation
- Usage
- Tailwind Alternative

Features

- Flexgrid: A flexible grid system based on CSS flexbox with 12-column layout support
- FlexgridItem: Grid items with configurable span, responsive breakpoints, and auto-sizing

Installation

``bash
npm install @versini/ui-system
`

> Note: This component requires TailwindCSS and the @versini/ui-styles plugin for proper styling. See the installation documentation for complete setup instructions.

Usage

$3

`tsx
import { Flexgrid } from "@versini/ui-system/flexgrid";
import { FlexgridItem } from "@versini/ui-system/flexgrid-item";

function App() {
return (

Left column
Right column

);
}
`

$3

`tsx
columnGap={2}
rowGap={1}
alignHorizontal="center"
alignVertical="stretch"
>
Item 1
Item 2
Item 3

`

$3

`tsx


Responsive item


Another responsive item


`

$3

`tsx

Auto-growing item
Fixed width item

`

Tailwind Alternative

While Flexgrid and FlexgridItem provide a convenient abstraction, the same layouts can often be achieved using Tailwind CSS flex utilities directly. In many cases, using Tailwind directly may be a better long-term approach as it reduces component dependencies and leverages standard CSS patterns.

$3

Flexgrid/FlexgridItem:

`tsx

Left column
Right column

`

Tailwind Alternative:

`tsx


`tsx
columnGap={2}
rowGap={1}
alignHorizontal="center"
alignVertical="stretch"
>
Item 1
Item 2
Item 3

`

Tailwind Alternative:

`tsx


`tsx


Responsive item


Another responsive item


`

Tailwind Alternative:

`tsx


`tsx

Auto-growing item
Fixed width item

`

Tailwind Alternative:

`tsx


2. Simplified API: The span prop with 12-column abstraction is more intuitive than remembering Tailwind's fractional basis classes.

3. Responsive Object Syntax: The object-based responsive configuration ({ fallback: 12, sm: 6 }) is more readable than multiple responsive classes.

4. Context-aware Spacing: The gap values are passed through React context to child items, ensuring consistent spacing without prop drilling.

However, for most use cases, Tailwind's flex utilities provide equivalent functionality with better performance (no JavaScript overhead) and broader ecosystem compatibility.

Migration Tool

$3

This package includes a CLI tool to help migrate existing Flexgrid components to native Tailwind CSS classes:

`bash


Using npx (recommended)

- Basic Flexgrid with standard props (columnGap, rowGap, direction, alignHorizontal, alignVertical)
- FlexgridItem with numeric spans (1-12) or "auto"
- Static responsive objects with simple breakpoint values
- Standard className preservation

✅ Examples of successful conversions:

`tsx
// Before

Content
Content


// After


- Nested Flexgrid components
- Dynamic expressions in props (span={isVisible ? 6 : 12})
- Function calls in props (span={getSpan()})
- Prop spreading ({...props})
- Template literals or complex objects
- Ternary operators, logical operators, or method calls

⚠️ Examples of preserved code:

`tsx
// Before (preserved due to complexity)
Dynamic content;

// After (preserved with comment)
{
/ TODO: Convert manually - Complex FlexgridItem with nested components or complex expressions /
}
Dynamic content;
`

#### Usage Tips

1. Run on individual files for better control and review
2. Review preserved components marked with TODO: Convert manually comments
3. Test thoroughly after conversion to ensure functionality is preserved
4. Handle responsive objects manually for complex breakpoint logic
5. Remove unused imports if no other @versini/ui-system` components remain

#### Why This Approach?

The CLI takes a conservative approach to ensure it never breaks your existing code or changes the intended behavior. Complex scenarios are preserved with clear comments explaining why manual conversion is needed, allowing you to:

- Maintain confidence that converted code works identically
- Focus manual effort only where truly needed
- Understand limitations through clear documentation
- Proceed incrementally file by file at your own pace

This ensures the tool helps accelerate migration while maintaining code quality and preserving the original intent of complex component usage.