Foldable UI - Component Library Setup

Goal

Create a pragmatic, reusable React component library called foldable-ui to serve as the frontend foundation for future projects. This library will include layout primitives and minimal wrapper components for fast prototyping and clear documentation.

It should:

• Be usable out-of-the-box (no CLI, no installer)
• Live inside the monorepo at packages/foldable-ui
• Integrate cleanly with Storybook for copy-pasteable usage examples
• Support both unstyled (Foundation-style) and themed (ShadCN-style) usage paths

First Steps

Scaffold the foldable-ui package:

mkdir packages/foldable-ui
cd packages/foldable-ui
pnpm init

Initial folder structure:

foldable-ui/
├── src/
│   ├── components/ # Simple UI wrappers
│   ├── layouts/ # Composable layout primitives
│   └── index.ts # Export hub
├── package.json
└── tsconfig.json

Use in conjunction with:

• packages/storybook → Story-based documentation
• packages/themes → Spacing, color, and typography tokens

Prioritized Component List (v1)

These are layout primitives that serve as the foundation of most UI compositions. Prioritize these for immediate use:

1. Stack

Pattern: Vertically spaced elements with consistent gap Why: Replaces margin-based spacing between blocks (e.g., typography) with a consistent layout primitive.

2. Group

Pattern: Horizontally spaced group of items that wraps as needed Why: Useful for buttons, tag groups, inline controls. Replaces old button-group or manual flex spacing.

3. Box (Callout)

Pattern: Padded content container, optionally bordered or shadowed Why: Used for alerts, visual grouping, card-like surfaces.

4. Asym2Up

Pattern: Asymmetrical layout with a main and sidebar column Why: Ideal for layouts like article + aside, nav + content, etc.

5. ScreenCentered

Pattern: Center content both vertically and horizontally Why: Used in modals, splash screens, onboarding states, etc.

Usage Philosophy

Foldable UI is built around these core ideas:

• Composable over configurable: These components are simple layout wrappers using div, flex, grid, and Tailwind utility props.
• Design-token ready: Spacing, color, and radius values should be derived from packages/themes.
• Zero setup: You install the package and start importing — no installer, no CLI, no config wizard.
• Storybook-first: Every component should have an accompanying Storybook story designed for quick scanning and copy-paste reuse.
• Foundation-style DNA: The unstyled component philosophy leans on ZURB’s clarity and simplicity, while staying modern.

Future Work - Full Pattern Inventory

These are useful patterns to consider after the core five are implemented:

Pattern Name	Description
Grid / AutoGrid	Auto-fitting grid items with defined min/max size
Container	Horizontally centered content with max-width constraints
Masonry	Staggered grid layout for uneven height content
MediaObject	Classic image-left + content-right block
StickyFooter	Footer pinned to bottom of viewport when content is short
SidebarNav	Responsive sidebar navigation that collapses into a drawer
ScrollRegion	Scrollable container with fixed header or footer
CoverCard	Section or card that expands to fill available space
ZStack	Overlapping elements with z-index control
SplitHero	Two-column hero layout with image and text
Overlay	Floating element above others — used for modals, tooltips, badges
Inset	Internal padding for bounded elements
Framed	Bordered + padded visual frame
OverflowWrap	Layout that handles overflow/scroll edge cases
SidebarPage	Page layout with consistent nav/content separation

These can be progressively added to match future project needs.

Summary

Start by building packages/foldable-ui and implementing 5 foundational layout components: Stack, Group, Box, Asym2Up, and ScreenCentered. Co-locate Storybook documentation to make them copy-paste friendly and easy to use. Focus on clear naming, minimal API surface, and zero-config usage.

Once this foundation is solid, expand into more layout and composition patterns as project demands grow.