@frooxi-labs/adaptive-ui

The Adaptive Layout Engine for React. A framework-agnostic, type-safe layout system that enforces consistent design tokens and responsive behavior across the Frooxi Venture Portfolio.

Contributing

Frooxi Labs enforces strict engineering standards. Please review our Contribution Guidelines for:

• Architectural Philosophy ("Three Laws of the Engine")
• TypeScript Standards
• Pull Request Protocol Portfolio.

🚀 Installation

npm install @frooxi-labs/adaptive-ui
# Required Peer Dependencies
npm install tailwindcss clsx

📚 Core Concepts

1. The Prop-Driven Model

Instead of navigating long strings of Tailwind utility classes (className="flex flex-col p-4 md:p-8..."), this library allows you to define layout through strongly typed props.

Why?

• Safety: You cannot pass invalid values (e.g., p="13px" will error; p="4" is valid).
• Readability: Separates Layout (Structure) from Decoration (Visuals).
• Speed: Autocomplete works for all design tokens.

2. The Universal Box

The <Box /> component is the atom of this library. Every other component (Stack, Flex, Grid) is just a specialized Box.

If you master Box, you master the entire system.

📖 Usage Guide

Polymorphism (as prop)

You can render a Box as any HTML element while keeping all layout capabilities. This prevents "Div Soup" and maintains semantic HTML.

import { Box } from '@frooxi-labs/adaptive-ui';

// Renders a <nav> tag
<Box as="nav" p="4" bg="white" shadow="sm">
  
  // Renders a <ul> tag
  <Box as="ul" display="flex" gap="4">
    
    // Renders <li> tags
    <Box as="li">Home</Box>
    <Box as="li">About</Box>

  </Box>
</Box>

Adaptive Responsiveness (Array Syntax)

We use a Tuple-Based Syntax to handle breakpoints. This enforces a "Mobile-First" approach. The values map to your Tailwind breakpoints: [Base, sm, md, lg, xl, 2xl].

<Box
  // Mobile: 16px (p-4)
  // Tablet: 24px (p-6)
  // Desktop: 32px (p-8)
  p={['4', '6', '8']}

  // Mobile: Block layout
  // Desktop: Flex layout
  display={['block', 'flex']}
  
  // Mobile: 100% width
  // Desktop: 50% width
  w={['full', '1/2']}
>
  This content adapts automatically.
</Box>

Vertical Stacks (<Stack>)

The most common layout pattern on the web is a vertical list of items with even spacing. Stack handles this automatically via the gap prop.

import { Stack, Text, Box } from '@frooxi-labs/adaptive-ui';

<Stack gap="4">
  <Box>
    <Text as="h2" size="xl" weight="bold">Card Title</Text>
    <Text color="gray-500">Subtitle description here</Text>
  </Box>

  <Box h="1px" bg="gray-200" /> {/* Divider */}

  <Stack gap="2">
    <Text>• Feature A</Text>
    <Text>• Feature B</Text>
  </Stack>
</Stack>

Grid Layouts (<Grid>)

For dashboard-style or complex 2D layouts.

import { Grid, GridItem } from '@frooxi-labs/adaptive-ui';

// 1 Column on Mobile, 3 on Desktop
<Grid columns={[1, 1, 3]} gap="6">
  
  // Spans 2 columns on Desktop
  <GridItem colSpan={[1, 1, 2]}>
    <MainChart />
  </GridItem>

  <GridItem>
    <SidebarWidget />
  </GridItem>

</Grid>

⚡ API Reference

All components support the following prop categories.

1. Layout Properties

| Prop | Type | Description | | :--- | :--- | :--- | | display | block, flex, grid, none, inline-block | CSS Display property | | w, h | Tailwind Spacing Scale (4, full, screen, etc.) | Width and Height | | size | Tailwind Spacing Scale | Sets both Width and Height | | position | relative, absolute, fixed, sticky | CSS Position | | top, bot, left, right | Tailwind Spacing Scale | Position coordinates | | inset | Tailwind Spacing Scale | Sets all 4 coordinates | | zIndex | 0, 10, 20, 30, 40, 50, auto | Stack order | | overflow | hidden, auto, scroll, visible | Content clipping |

2. Spacing Properties

| Prop | Description | | :--- | :--- | | m, mx, my, mt, mb, ml, mr | Margins (Outer spacing) | | p, px, py, pt, pb, pl, pr | Padding (Inner spacing) | | gap, gapX, gapY | Gap between Flex/Grid children |

3. Visual Styling

| Prop | Type | Description | | :--- | :--- | :--- | | bg | Tailwind Colors (slate-50, bg-blue-500...) | Background Color | | color | Tailwind Colors (text-slate-900...) | Text Color | | border | 0, 1, 2, 4, 8 | Border Width | | borderColor | Tailwind Colors | Border Color | | radius | sm, md, lg, full, none | Border Radius | | shadow | sm, md, lg, xl, none | Box Shadow | | opacity | 0 to 100 step 5 | Opacity |

4. Typography (<Text>)

Using the <Text /> primitive ensures consistent type scaling.

| Prop | Details | | :--- | :--- | | size | xs, sm, base, lg, xl -> 9xl | | weight | thin -> black | | align | left, center, right, justify | | leading | Line Height (none, tight, relaxed...) | | tracking | Letter Spacing (tighter, widest...) |

🧩 Advanced Features

Conditional Visibility (Show/Hide)

Declarative visibility control based on breakpoints. Prevents complex CSS media queries.

import { Show, Hide } from '@frooxi-labs/adaptive-ui';

// Render ONLY on "Large" screens and up
<Show above="lg">
  <DesktopSidebar />
</Show>

// Render ONLY on "Medium" screens and down
<Hide above="md">
  <MobileDrawer />
</Hide>

The Container

Standardized viewport constraint for page content.

import { Container } from '@frooxi-labs/adaptive-ui';

// Automatically centered, max-width constrained
<Container>
  <PageContent />
</Container>

License

Distributed under the Frooxi Labs Public License (v1.0). Free for commercial app development. Resale of the library itself is prohibited. Copyright © 2026 Frooxi Labs.