Zen Flow UI

Philosophy

Zen Flow UI synthesizes timeless design principles with modern web aesthetics, drawing inspiration from:

• Japanese Minimalism: The beauty of negative space and restraint
• Swiss Design: Mathematical precision and systematic thinking
• Material Design: Meaningful motion and depth
• Brutalist Web Design: Raw functionality over decoration

Every design decision flows through three filters:

1. Does it serve the user's goal? (Function)
2. Is it visually coherent? (Form)
3. Does it spark joy? (Delight)

Features

✨ 20+ Production-Ready Components - Carefully crafted with attention to detail
🎨 Japanese-Inspired Design - Minimalist aesthetics with purposeful interactions
♿ Accessibility First - WCAG compliant with full keyboard navigation
🎭 Motion-Sensitive - Respects prefers-reduced-motion settings
🔧 TypeScript Native - Full type safety and excellent DX
🌙 Dark Mode Ready - CSS custom properties for easy theming
📦 Tree Shakable - Import only what you need
⚡ Performance Optimized - No inline style anti-patterns, clean CSS

Installation

npm install @gurusharan3107/zen-flow-ui

Dependencies

Install the required peer dependencies:

npm install react react-dom
npm install class-variance-authority clsx tailwind-merge framer-motion

Setup

1. Import global styles in your app:

import '@gurusharan3107/zen-flow-ui/styles/globals.css';

2. Add utilities (create src/lib/utils.ts):

import { type ClassValue, clsx } from 'clsx';
import { twMerge } from 'tailwind-merge';

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

3. Wrap your app with ToastProvider (if using notifications):

import { ToastProvider } from '@gurusharan3107/zen-flow-ui';

function App() {
  return (
    <ToastProvider>
      {/* Your app content */}
    </ToastProvider>
  );
}

Quick Start

Here's a simple example to get you started:

import React from 'react';
import { Button, Card, CardHeader, CardTitle, CardContent } from '@gurusharan3107/zen-flow-ui';
import '@gurusharan3107/zen-flow-ui/styles/globals.css';

function App() {
  return (
    <div className="p-8">
      <Card className="max-w-md">
        <CardHeader>
          <CardTitle>Welcome to Zen Flow UI</CardTitle>
        </CardHeader>
        <CardContent>
          <p className="mb-4">A minimalist component library with Japanese design principles.</p>
          <Button>Get Started</Button>
        </CardContent>
      </Card>
    </div>
  );
}

export default App;

Available Components

Form & Input Components

• Button - Interactive button with multiple variants and subtle animations
• Input - Text input with floating labels and elegant focus states
• Textarea - Multi-line text input with auto-resize capabilities
• Select - Dropdown select with keyboard navigation and search
• Toggle - Switch component with smooth animations
• RadioGroup - Radio button groups with proper accessibility
• Slider - Range slider with tooltips and custom formatting

Layout & Navigation

• Card - Container for related content with hover effects
• Accordion - Collapsible content sections with smooth animations
• Tabs - Tab navigation with keyboard support
• Breadcrumb - Navigation breadcrumbs with automatic path detection

Data Display

• DataTable - Advanced table with sorting, filtering, and pagination
• Progress - Linear and circular progress indicators
• Alert - Status messages with multiple variants

Overlay Components

• Modal - Overlay dialog with backdrop blur and smooth transitions
• Dialog - Accessible dialog component with proper focus management
• Popover - Floating content with smart positioning
• Tooltip - Contextual information with hover and focus states

Utility Components

• Command - Command palette with search and keyboard navigation
• Notification - Toast notifications with auto-dismiss

Usage Examples

Button with Loading State

import { Button } from '@gurusharan3107/zen-flow-ui';

function Example() {
  const [loading, setLoading] = useState(false);
  
  return (
    <Button 
      loading={loading} 
      onClick={() => setLoading(true)}
      variant="primary"
    >
      {loading ? 'Processing...' : 'Submit'}
    </Button>
  );
}

Card with Hover Effects

import { Card, CardHeader, CardTitle, CardContent } from '@gurusharan3107/zen-flow-ui';

function Example() {
  return (
    <Card variant="elevated" className="max-w-md">
      <CardHeader>
        <CardTitle>Minimalist Design</CardTitle>
      </CardHeader>
      <CardContent>
        <p>Every element serves a purpose in this carefully crafted interface.</p>
      </CardContent>
    </Card>
  );
}

Form with Validation

import { Input, Button, Card, CardContent } from '@gurusharan3107/zen-flow-ui';

function Example() {
  const [email, setEmail] = useState('');
  const [error, setError] = useState('');
  
  return (
    <Card className="max-w-md">
      <CardContent className="space-y-4">
        <Input
          label="Email Address"
          type="email"
          value={email}
          onChange={(e) => setEmail(e.target.value)}
          error={error}
          helperText="We'll never share your email"
        />
        <Button className="w-full">Subscribe</Button>
      </CardContent>
    </Card>
  );
}

Interactive Data Table

import { DataTable } from '@gurusharan3107/zen-flow-ui';

const columns = [
  { key: 'name', header: 'Name', sortable: true },
  { key: 'email', header: 'Email', sortable: true },
  { key: 'role', header: 'Role' },
];

const data = [
  { name: 'John Doe', email: '[email protected]', role: 'Developer' },
  { name: 'Jane Smith', email: '[email protected]', role: 'Designer' },
];

function Example() {
  return (
    <DataTable
      columns={columns}
      data={data}
      searchable
      pagination
      pageSize={10}
    />
  );
}

Customization

Tailwind CSS Configuration

Add Zen Flow colors to your Tailwind config:

// tailwind.config.js
module.exports = {
  content: [
    "./src/**/*.{js,ts,jsx,tsx}",
    "./node_modules/@gurusharan3107/zen-flow-ui/dist/**/*.js"
  ],
  theme: {
    extend: {
      colors: {
        'zen-void': '#0a0a0a',
        'zen-ink': '#1a1a1a',
        'zen-shadow': '#2a2a2a',
        'zen-stone': '#4a4a4a',
        'zen-mist': '#8a8a8a',
        'zen-cloud': '#dadada',
        'zen-paper': '#fafafa',
        'zen-light': '#ffffff',
        'zen-accent': '#ff4757',
        'zen-water': '#3742fa',
        'zen-leaf': '#26de81',
        'zen-sun': '#fed330',
      },
      animation: {
        'shimmer': 'shimmer 2s linear infinite',
        'accordion-down': 'accordion-down 0.2s ease-out',
        'accordion-up': 'accordion-up 0.2s ease-out',
      },
      keyframes: {
        'shimmer': {
          '0%': { transform: 'translateX(-100%)' },
          '100%': { transform: 'translateX(100%)' },
        },
        'accordion-down': {
          from: { height: 0 },
          to: { height: 'var(--radix-accordion-content-height)' },
        },
        'accordion-up': {
          from: { height: 'var(--radix-accordion-content-height)' },
          to: { height: 0 },
        },
      },
    },
  },
  plugins: [],
};

CSS Custom Properties

Override design tokens using CSS custom properties:

:root {
  --zen-accent: #your-brand-color;
  --zen-water: #your-primary-color;
  --zen-space-md: 20px;
}

/* Dark mode support */
@media (prefers-color-scheme: dark) {
  :root {
    --zen-light: #0a0a0a;
    --zen-void: #ffffff;
  }
}

Performance & Best Practices

Code Quality

• ✅ No Inline Style Anti-patterns - All styling uses CSS classes and design tokens
• ✅ Optimized Bundle Size - Tree-shakable exports and efficient code splitting
• ✅ TypeScript Native - Full type safety with no runtime overhead

Accessibility

• ✅ WCAG 2.1 AA Compliant - Tested with screen readers and keyboard navigation
• ✅ Focus Management - Proper focus trapping and restoration in modals
• ✅ ARIA Labels - Comprehensive labeling for assistive technologies
• ✅ Keyboard Navigation - Full keyboard support for all interactive elements

Motion & Animation

• ✅ Respects User Preferences - Honors prefers-reduced-motion settings
• ✅ Purposeful Motion - Animations enhance UX without being distracting
• ✅ Smooth Transitions - GPU-accelerated animations for 60fps performance

Browser Support

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

Troubleshooting

Common Issues

CSS not loading properly:

• Ensure you've imported the global styles: import '@gurusharan3107/zen-flow-ui/styles/globals.css'
• Check that Tailwind CSS is configured properly in your project

TypeScript errors:

• Install required type dependencies: npm install @types/react @types/react-dom
• Ensure your tsconfig.json includes the jsx option

Component styling issues:

• Verify that clsx and tailwind-merge are installed
• Check that the cn utility function is properly imported and configured

Animation performance:

• Enable hardware acceleration: transform3d(0,0,0) or will-change: transform
• Consider using prefers-reduced-motion for users with motion sensitivity

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development

# Clone the repository
git clone https://github.com/ingpoc/zen-flow-ui.git

# Install dependencies
npm install

# Start development
npm run dev

# Run tests
npm run test

# Build library
npm run build

Changelog

v2.1.1 (Latest)

• ✅ Fixed inline style anti-patterns across all components
• ✅ Improved TypeScript definitions for better DX
• ✅ Enhanced accessibility features
• ✅ Optimized bundle size and performance
• ✅ Updated documentation and examples

License

MIT License - see LICENSE for details.

Built with ❤️ by the Zen Flow Team

Documentation • NPM Package • Issues