FlowUIX

AI-First, HTML-Native UI Component Library

FlowUIX is a modern, lightweight UI component library built on TailwindCSS with first-class support for HTMX and Alpine.js. It's designed for developers who prefer HTML-first development and want to build dynamic, interactive applications without heavy JavaScript frameworks.

Features

• HTML-Native: Write pure HTML with utility classes
• Framework Agnostic: Works with any JavaScript framework or none at all
• HTMX Ready: Built-in support for dynamic, server-driven interactions
• Alpine.js Compatible: Perfect for reactive, client-side enhancements
• AI-Friendly: Simple, predictable patterns that AI tools can understand
• Tailwind Plugin: Easy integration with your Tailwind setup
• Zero JavaScript: Components work without JavaScript by default
• Accessible: Built with WCAG guidelines in mind
• Lightweight: Minimal footprint, maximum flexibility

Why HTML-First?

1. Simplicity: Less JavaScript means less complexity
2. Performance: Smaller bundle sizes, faster load times
3. Server-Side Rendering: Perfect for SSR frameworks
4. Progressive Enhancement: Works even when JavaScript fails
5. Developer Experience: Faster iteration, easier debugging
6. AI Compatibility: Clear patterns for AI code generation

Installation

npm install flowuix

Or using yarn:

yarn add flowuix

Or using pnpm:

pnpm add flowuix

Quick Start

1. Add to Tailwind Config

// tailwind.config.js
export default {
  content: [
    './src/**/*.{html,js,jsx,ts,tsx}',
  ],
  plugins: [
    require('flowuix/plugin')
  ]
}

2. Use Components

<button class="fx-btn fx-btn-primary">Click Me</button>

3. Add HTMX (Optional)

<script src="https://unpkg.com/[email protected]"></script>

<button
  class="fx-btn fx-btn-primary"
  hx-get="/api/data"
  hx-target="#result">
  Load Data
</button>

<div id="result"></div>

4. Add Alpine.js (Optional)

<script defer src="https://cdn.jsdelivr.net/npm/[email protected]/dist/cdn.min.js"></script>

<div x-data="{ count: 0 }">
  <button class="fx-btn fx-btn-primary" @click="count++">
    Clicked <span x-text="count"></span> times
  </button>
</div>

Components

Buttons

Multiple variants and sizes:

<!-- Variants -->
<button class="fx-btn fx-btn-primary">Primary</button>
<button class="fx-btn fx-btn-secondary">Secondary</button>
<button class="fx-btn fx-btn-success">Success</button>
<button class="fx-btn fx-btn-danger">Danger</button>
<button class="fx-btn fx-btn-outline">Outline</button>

<!-- Sizes -->
<button class="fx-btn fx-btn-primary fx-btn-sm">Small</button>
<button class="fx-btn fx-btn-primary">Medium</button>
<button class="fx-btn fx-btn-primary fx-btn-lg">Large</button>

Cards

Flexible card layouts:

<div class="fx-card">
  <div class="fx-card-header">
    Card Header
  </div>
  <div class="fx-card-body">
    <h3 class="text-lg font-semibold mb-2">Card Title</h3>
    <p class="text-gray-600">Card content goes here.</p>
  </div>
  <div class="fx-card-footer">
    <button class="fx-btn fx-btn-primary fx-btn-sm">Action</button>
  </div>
</div>

Alerts

Contextual notifications:

<div class="fx-alert fx-alert-info">
  <strong>Info:</strong> This is an informational message.
</div>

<div class="fx-alert fx-alert-success">
  <strong>Success!</strong> Your action was completed.
</div>

<div class="fx-alert fx-alert-warning">
  <strong>Warning:</strong> Please review this carefully.
</div>

<div class="fx-alert fx-alert-error">
  <strong>Error:</strong> Something went wrong.
</div>

Badges

Status indicators:

<span class="fx-badge fx-badge-primary">Primary</span>
<span class="fx-badge fx-badge-success">Success</span>
<span class="fx-badge fx-badge-warning">Warning</span>
<span class="fx-badge fx-badge-danger">Danger</span>

HTMX Examples

Dynamic Content Loading

<button
  class="fx-btn fx-btn-primary"
  hx-get="/api/content"
  hx-target="#content"
  hx-swap="innerHTML">
  Load Content
</button>

<div id="content" class="fx-card mt-4">
  <div class="fx-card-body">
    Content will appear here...
  </div>
</div>

Form Submission

<form hx-post="/api/submit" hx-target="#result">
  <input type="text" name="name" class="border rounded px-3 py-2">
  <button type="submit" class="fx-btn fx-btn-primary">
    Submit
  </button>
</form>

<div id="result" class="mt-4"></div>

Live Search

<input
  type="search"
  name="q"
  placeholder="Search..."
  class="border rounded px-3 py-2"
  hx-get="/api/search"
  hx-trigger="keyup changed delay:300ms"
  hx-target="#results">

<div id="results" class="mt-4"></div>

Alpine.js Examples

Counter

<div x-data="{ count: 0 }">
  <button class="fx-btn fx-btn-primary" @click="count++">
    Clicked <span x-text="count"></span> times
  </button>
</div>

Dismissible Alert

<div class="fx-alert fx-alert-info" x-data="{ show: true }" x-show="show" x-transition>
  <div class="flex items-start justify-between">
    <div>
      <strong>Info:</strong> This alert can be dismissed.
    </div>
    <button @click="show = false" class="ml-4">×</button>
  </div>
</div>

Collapsible Card

<div x-data="{ open: true }">
  <div class="fx-card" x-show="open" x-transition>
    <div class="fx-card-body">
      <p>This card can be toggled!</p>
      <button @click="open = false" class="fx-btn fx-btn-sm mt-2">
        Close
      </button>
    </div>
  </div>
  <button @click="open = true" x-show="!open" class="fx-btn fx-btn-primary">
    Show Card
  </button>
</div>

Design Tokens

FlowUIX provides design tokens for consistent theming:

import { colors, shadows, radius, spacing } from 'flowuix/package/tokens.js';

// Use in your custom components
console.log(colors.primary[500]); // #3b82f6

Utility Functions

Helper functions for working with components:

import { classNames, createHtmxButton } from 'flowuix/package/utils.js';

// Combine classes
const classes = classNames('fx-btn', 'fx-btn-primary', customClass);

// Create HTMX button
const button = createHtmxButton({
  text: 'Load Data',
  variant: 'primary',
  url: '/api/data',
  target: '#result'
});

Project Structure

flowuix/
├── package/              # Core library
│   ├── index.js         # Tailwind plugin (CJS)
│   ├── components/      # Component definitions (ES6)
│   ├── tokens.js        # Design tokens (ES6)
│   └── utils.js         # Utility functions (ES6)
├── demo/                # Vite playground
│   ├── index.html
│   ├── components/
│   └── vite.config.js
├── docs/                # Nextra documentation
│   └── pages/
├── package.json
├── tailwind.config.js
└── tsup.config.ts

Development

Run Demo

npm run dev

Visit http://localhost:3000 to see the demo playground.

Run Documentation

npm run docs

Visit http://localhost:3000 to see the documentation site.

Build Package

npm run build

Roadmap

• [ ] More components (modals, dropdowns, navigation)
• [ ] Dark mode support
• [ ] Additional design tokens
• [ ] TypeScript type definitions
• [ ] Component variants system
• [ ] Animation utilities
• [ ] Form components
• [ ] Data table components
• [ ] Advanced HTMX patterns
• [ ] Storybook integration

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

git clone https://github.com/yourusername/flowuix.git
cd flowuix
npm install
npm run dev

Philosophy

FlowUIX is built on these principles:

1. HTML First: HTML is the foundation, JavaScript is the enhancement
2. Progressive Enhancement: Core functionality works without JS
3. Server-Driven: Embrace server-side rendering and HTMX
4. Minimal Dependencies: Keep the footprint small
5. AI Compatibility: Patterns that AI tools can understand and generate
6. Developer Experience: Fast, intuitive, and enjoyable to use

License

MIT License - see LICENSE file for details

Acknowledgments

• Built with TailwindCSS
• Inspired by HTMX
• Enhanced with Alpine.js
• Documentation powered by Nextra

Links

• Documentation
• GitHub
• NPM
• Issues

Support

• Open an issue for bugs or feature requests
• Star the repo if you find it useful
• Share with others who might benefit

Made with ❤️ for the HTML-first community