@versini/ui-system

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

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

Basic Grid Layout

import { Flexgrid, FlexgridItem } from "@versini/ui-system";

function App() {
  return (
    <Flexgrid>
      <FlexgridItem span={6}>Left column</FlexgridItem>
      <FlexgridItem span={6}>Right column</FlexgridItem>
    </Flexgrid>
  );
}

Grid with Gaps and Alignment

<Flexgrid
  columnGap={2}
  rowGap={1}
  alignHorizontal="center"
  alignVertical="stretch"
>
  <FlexgridItem span={4}>Item 1</FlexgridItem>
  <FlexgridItem span={4}>Item 2</FlexgridItem>
  <FlexgridItem span={4}>Item 3</FlexgridItem>
</Flexgrid>

Responsive Layout

<Flexgrid columnGap={1}>
  <FlexgridItem span={{ fallback: 12, sm: 6, md: 4, lg: 3 }}>
    Responsive item
  </FlexgridItem>
  <FlexgridItem span={{ fallback: 12, sm: 6, md: 8, lg: 9 }}>
    Another responsive item
  </FlexgridItem>
</Flexgrid>

Auto-sizing and Direction

<Flexgrid direction="column" columnGap={1}>
  <FlexgridItem span="auto">Auto-growing item</FlexgridItem>
  <FlexgridItem span={6}>Fixed width item</FlexgridItem>
</Flexgrid>

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.

Basic Grid Layout

Flexgrid/FlexgridItem:

<Flexgrid>
  <FlexgridItem span={6}>Left column</FlexgridItem>
  <FlexgridItem span={6}>Right column</FlexgridItem>
</Flexgrid>

Tailwind Alternative:

<div className="flex flex-wrap">
  <div className="basis-6/12 max-w-full">Left column</div>
  <div className="basis-6/12 max-w-full">Right column</div>
</div>

Grid with Gaps and Alignment

Flexgrid/FlexgridItem:

<Flexgrid
  columnGap={2}
  rowGap={1}
  alignHorizontal="center"
  alignVertical="stretch"
>
  <FlexgridItem span={4}>Item 1</FlexgridItem>
  <FlexgridItem span={4}>Item 2</FlexgridItem>
  <FlexgridItem span={4}>Item 3</FlexgridItem>
</Flexgrid>

Tailwind Alternative:

<div className="flex flex-wrap justify-center items-stretch gap-x-2 gap-y-1">
  <div className="basis-4/12 max-w-full">Item 1</div>
  <div className="basis-4/12 max-w-full">Item 2</div>
  <div className="basis-4/12 max-w-full">Item 3</div>
</div>

Responsive Layout

Flexgrid/FlexgridItem:

<Flexgrid columnGap={1}>
  <FlexgridItem span={{ fallback: 12, sm: 6, md: 4, lg: 3 }}>
    Responsive item
  </FlexgridItem>
  <FlexgridItem span={{ fallback: 12, sm: 6, md: 8, lg: 9 }}>
    Another responsive item
  </FlexgridItem>
</Flexgrid>

Tailwind Alternative:

<div className="flex flex-wrap gap-x-1">
  <div className="basis-full sm:basis-6/12 md:basis-4/12 lg:basis-3/12 max-w-full">
    Responsive item
  </div>
  <div className="basis-full sm:basis-6/12 md:basis-8/12 lg:basis-9/12 max-w-full">
    Another responsive item
  </div>
</div>

Auto-sizing and Direction

Flexgrid/FlexgridItem:

<Flexgrid direction="column" columnGap={1}>
  <FlexgridItem span="auto">Auto-growing item</FlexgridItem>
  <FlexgridItem span={6}>Fixed width item</FlexgridItem>
</Flexgrid>

Tailwind Alternative:

<div className="flex flex-col gap-x-1">
  <div className="basis-auto max-w-full grow">Auto-growing item</div>
  <div className="basis-6/12 max-w-full">Fixed width item</div>
</div>

What Flexgrid Provides That's Hard to Replicate

While most Flexgrid functionality can be achieved with Tailwind, there are a few areas where Flexgrid provides unique value:

1. Custom Gap System: Flexgrid uses a custom gap ratio (0.25rem per unit) with negative margins and padding, which creates a different spacing behavior than Tailwind's standard gap utilities.

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

Flexgrid to Tailwind CLI Converter

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

# Using npx (recommended)
npx @versini/ui-system/flexgrid-to-tw --file src/components/MyComponent.tsx

# Or after installation
node ./node_modules/@versini/ui-system/dist/cli/flexgrid-to-tw.js --file src/components/MyComponent.tsx

Features

• Conservative approach: Only converts simple, unambiguous cases
• Complex preservation: Preserves complex scenarios with explanatory comments
• Import management: Automatically handles import statements
• Detailed reporting: Shows conversion statistics and warnings

What Gets Converted

✅ Simple cases that are converted automatically:

• 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:

// Before
<Flexgrid columnGap={2} alignHorizontal="center">
  <FlexgridItem span={4}>Content</FlexgridItem>
  <FlexgridItem span={8}>Content</FlexgridItem>
</Flexgrid>

// After
<div className="flex flex-wrap justify-center gap-x-2">
  <div className="box-border max-w-full basis-4/12">Content</div>
  <div className="box-border max-w-full basis-8/12">Content</div>
</div>

⚠️ Complex cases that are preserved with comments:

• 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:

// Before (preserved due to complexity)
<FlexgridItem span={isVisible ? 6 : 12}>Dynamic content</FlexgridItem>;

// After (preserved with comment)
{
  /* TODO: Convert manually - Complex FlexgridItem with nested components or complex expressions */
}
<FlexgridItem span={isVisible ? 6 : 12}>Dynamic content</FlexgridItem>;

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.