HYDN UI

A modern React component library built with TypeScript, Tailwind CSS, and optimized with Vite.

Overview

HYDN UI is a comprehensive design system and component library that provides a collection of reusable, accessible, and customizable React components. The library includes everything from basic form elements to complex data visualization components.

Features

• 🎨 Modern Design System - Clean, consistent, and professional UI components
• ⚡ Built with Vite - Fast builds and optimal bundle size
• 🎯 TypeScript - Full type safety and excellent developer experience
• 🎨 Tailwind CSS - Utility-first CSS framework for rapid styling
• ♿ Accessible - Components built with accessibility in mind
• 🧪 Well Tested - Comprehensive test suite with Vitest
• 📱 Responsive - Mobile-first responsive design
• 🌲 Tree-Shakeable - Only bundle what you use

Table of Contents

• Installation
• Quick Start
• Usage Examples
• Component Categories
• Tree-Shaking
• Development
• Publishing
• CSS Class Validation
• Tech Stack
• Contributing

Installation

npm install @hyddenlabs/hydn-ui
# or
yarn add @hyddenlabs/hydn-ui
# or
pnpm add @hyddenlabs/hydn-ui

Quick Start

Basic Setup

import { ThemeProvider } from '@hyddenlabs/hydn-ui';
import '@hyddenlabs/hydn-ui/styles.css';

function App() {
  return (
    <ThemeProvider>
      <Card>
        <h1>Hello World</h1>
        <Input placeholder="Enter your name" />
        <Button>Submit</Button>
      </Card>
    </ThemeProvider>
  );
}

Note: The styles are automatically included when you import any component. You only need to ensure your bundler (Vite, Webpack, etc.) is configured to handle CSS imports.

Usage Examples

Forms

import { Button, Input, FormField, Card } from '@hyddenlabs/hydn-ui';

function LoginForm() {
  return (
    <Card>
      <FormField label="Email" required>
        <Input type="email" placeholder="Enter your email" />
      </FormField>

      <FormField label="Password" required>
        <Input type="password" placeholder="Enter your password" />
      </FormField>

      <Button variant="primary" fullWidth>
        Sign In
      </Button>
    </Card>
  );
}

Data Tables

import { DataTable } from '@hyddenlabs/hydn-ui';

const columns = [
  { accessorKey: 'name', header: 'Name' },
  { accessorKey: 'email', header: 'Email' },
  { accessorKey: 'status', header: 'Status' }
];

const data = [
  { name: 'John Doe', email: '[email protected]', status: 'active' },
  { name: 'Jane Smith', email: '[email protected]', status: 'inactive' }
];

function UserTable() {
  return <DataTable columns={columns} data={data} />;
}

Layouts

import { Container, Grid, Card, Heading } from '@hyddenlabs/hydn-ui';

function Dashboard() {
  return (
    <Container>
      <Heading level={1}>Dashboard</Heading>

      <Grid cols={3} gap="lg">
        <Card>
          <Heading level={3}>Total Users</Heading>
          <p>1,234</p>
        </Card>

        <Card>
          <Heading level={3}>Revenue</Heading>
          <p>$45,678</p>
        </Card>

        <Card>
          <Heading level={3}>Orders</Heading>
          <p>890</p>
        </Card>
      </Grid>
    </Container>
  );
}

Theme Customization

import { ThemeProvider, ColorModeToggle } from '@hyddenlabs/hydn-ui';

function App() {
  return (
    <ThemeProvider defaultTheme="dark">
      <header>
        <ColorModeToggle />
      </header>
      {/* Your app content */}
    </ThemeProvider>
  );
}

TypeScript Support

All components are fully typed. Import types directly:

import type { ButtonProps, InputProps, CardProps } from '@hyddenlabs/hydn-ui';

const customButton: ButtonProps = {
  variant: 'primary',
  size: 'lg',
  onClick: () => console.log('clicked')
};

Component Categories

Forms & Inputs

• Button, Button Group
• Input, Input Group, Textarea
• Select, Radio, Radio Group, Checkbox
• Slider, Switch, Calendar
• Form, Form Field, Fieldset

Data Display

• Avatar, Badge, Chip
• Table, Data Table, List
• Timeline, Code Block
• Empty State

Layout

• Card, Container, Grid
• Accordion, Drawer, Divider
• Page, Page Header, Section
• Hero, Feature Section, Footer
• Stack

Navigation

• Navbar, Nav, Sidebar
• Breadcrumbs, Dropdown
• Pagination, Stepper, Tabs

Feedback

• Alert, Dialog, Modal
• Toast, Tooltip, Popover
• Progress Bar, Spinner, Skeleton

Typography

• Heading, Text, Link, Code

System

• Theme Provider, Color Mode Toggle

Tree-Shaking

The library is built with full tree-shaking support. Modern bundlers (Vite, Webpack 5, Rollup) will automatically eliminate unused components:

// Only Button and its dependencies are bundled (~6KB)
import { Button } from '@hyddenlabs/hydn-ui';

// Multiple imports are also tree-shaken
import { Button, Input, Card } from '@hyddenlabs/hydn-ui';

Benefits

• ✅ Only pay for what you use
• ✅ Automatic dead code elimination with ESM
• ✅ Unminified source for better bundler optimization
• ✅ Modern tooling compatible

How It Works

The library is optimized for tree-shaking:

• ESM format - Modern bundlers can analyze and eliminate dead code
• Unminified - Preserves original code structure for better analysis
• sideEffects field - Tells bundlers what's safe to remove (CSS only)
• Named exports - Each component is individually importable
• No global side effects - Components don't execute code on import

Verification

To verify tree-shaking works:

1. Create a test project with Vite:

npm create vite@latest my-test -- --template react-ts
cd my-test
npm install @hyddenlabs/hydn-ui

2. Import a single component:

import { Button } from '@hyddenlabs/hydn-ui';

3. Build and check bundle size:

npm run build

You should see only ~6-8KB for Button, not the entire 118KB library.

Development

This repository contains both the component library and a showcase/documentation SPA.

Prerequisites

• Node.js (v18 or higher)
• npm, yarn, or pnpm

Local Development Setup

# Clone the repository
git clone https://github.com/hydn-co/hydn-ui.git
cd hydn-ui

# Install dependencies
npm install

# Start the development server (runs the showcase SPA)
npm run dev

# Run tests
npm test

# Build the library for publishing
npm run build

# Lint code
npm run lint

# Format code
npm run format

Scripts

| Command | Purpose | | --- | --- | | npm run dev | Start the showcase SPA (development server) | | npm run build | Build the library (ESM), CSS, and types | | npm test | Run the test suite (Vitest) | | npm run lint | Lint source and tests (ESLint) | | npm run lint:fix | Lint with auto-fix | | npm run format | Format code with Prettier | | npm run format:check | Check formatting (used in CI) |

See package.json for the full list of scripts.

Project Structure

src/
├── components/          # Reusable UI components (library)
│   ├── data-display/   # Data visualization components
│   ├── feedback/       # User feedback components
│   ├── forms/          # Form-related components
│   ├── layout/         # Layout and structural components
│   ├── navigation/     # Navigation components
│   ├── system/         # System-level components
│   └── typography/     # Text and typography components
├── showcase/            # Showcase/documentation SPA (not published)
│   ├── pages/          # Demo and application pages
│   └── ...
├── theme/               # Theme configuration and tokens
└── index.ts             # Main library entry (consumers import from here)

Publishing

Build the Library

npm run build

The library is ESM-only. The build generates:

• dist/index.js - ESM entry (tree-shakeable; additional modules under dist/ for tree-shaking)
• dist/index.d.ts - TypeScript declarations
• dist/style.css - Compiled Tailwind CSS styles
• Source maps for debugging

Publishing Process

1. Update Version

# Using npm version command (recommended)
npm version patch   # 1.0.0 -> 1.0.1
npm version minor   # 1.0.0 -> 1.1.0
npm version major   # 1.0.0 -> 2.0.0

2. Verify Build Output

Check the dist/ folder contains all required files.

3. Test Locally (Optional)

# In hydn-ui directory
npm link

# In your test project
npm link @hyddenlabs/hydn-ui

Or create a tarball:

npm pack
# This creates hyddenlabs-hydn-ui-x.x.x.tgz

4. Publish to npm

# Dry run (recommended first)
npm publish --dry-run

# Publish (public package)
npm publish --access public

# Or publish with a specific tag
npm publish --tag beta --access public

5. Verify Publication

• Check the package page: https://www.npmjs.com/package/@hyddenlabs/hydn-ui
• Test installation: npm install @hyddenlabs/hydn-ui

Automated Publishing (CI/CD)

The repository uses GitHub Actions (.github/workflows/publish.yml):

1. Set the version manually in package.json
2. Commit and push your changes
3. Run Actions → Publish Package → Run workflow

The workflow runs CI checks, reads the version from package.json, tags the commit, and publishes to npm.

Troubleshooting

Build Fails:

rm -rf dist node_modules
npm install
npm run build

Permission Denied:

npm whoami
npm access ls-packages @hyddenlabs

Post-Publish Checklist

• [ ] Verify package appears on npm
• [ ] Test installation in a fresh project
• [ ] Update CHANGELOG.md
• [ ] Create GitHub release with notes
• [ ] Announce release (if applicable)

CSS Class Validation

HYDN UI includes comprehensive CSS validation tools to ensure all Tailwind classes used in components are properly generated in the output CSS.

Why This Matters

When building a component library with Tailwind CSS, it's critical to ensure that:

• All classes used in components are actually generated in the final CSS
• No classes are accidentally misspelled or reference non-existent theme tokens
• The generated CSS file contains everything consumers need

Validation Methods

1. Automated Audit Script (Recommended)

Run the comprehensive audit to check all components:

npm run audit:css

This script:

• ✅ Extracts all className usages from your components
• ✅ Validates them against the generated dist/style.css
• ✅ Reports missing classes with file locations
• ✅ Identifies dynamic/computed classes (like z-[999])
• ✅ Filters out template literals and conditional logic

Example Output:

🔍 Auditing CSS classes...

📁 Found 90 component files
📄 CSS file size: 69.41 KB

🎨 Total unique classes found: 177

⚠️  Dynamic/computed classes (2):
   - z-[999]
   - min-w-[180px]

✅ All classes found in generated CSS!
✅ 176 classes validated successfully

2. CSS Validation Tests

Run only the CSS validation tests:

npm run test:css

This runs tests/css-validation.test.ts which:

• ✅ Checks for critical component classes
• ✅ Validates theme tokens (CSS custom properties)
• ✅ Ensures CSS file is not empty
• ✅ Integrates with CI/CD pipelines

3. Full Test Suite

All component tests also implicitly validate CSS classes:

npm test

Since tests check for specific classes (e.g., expect(button).toHaveClass('rounded-lg')), they will fail if classes aren't generated.

Best Practices

Run audit before publishing:

npm run audit:css && npm run build && npm test

Avoid dynamic class construction:

// ❌ Bad - class might not be generated
const sizeClass = `w-${size}`;
<div className={sizeClass} />;

// ✅ Good - explicit mapping
const sizeClasses = {
  sm: 'w-4',
  md: 'w-6',
  lg: 'w-8'
};
<div className={sizeClasses[size]} />;

CI/CD integration - The GitHub Actions workflows automatically run CSS validation on every push and before publishing.

Validation Commands Summary

| Command | Purpose | | ------------------- | ------------------------------------- | | npm run audit:css | Comprehensive class validation | | npm run test:css | Quick CSS validation tests | | npm test | Full test suite (includes CSS checks) |

Tech Stack

• React 19 - UI library
• TypeScript - Type safety
• Vite - Library build and development server
• Tailwind CSS - Styling
• React Router - Client-side routing (showcase only)
• Vitest - Testing framework
• Testing Library - Component testing utilities
• Tabler Icons - Icon library

Contributing

See CONTRIBUTING.md for how to run the repo, run tests, and submit changes. In short:

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

License

This project is private and proprietary to HYDN Co.

Support

For questions and support, please contact the HYDN development team.