@cycomdatasystems/headwindui
v1.3.0
Published
A React UI component library built with Tailwind CSS, Headless UI, and Motion
Maintainers
aaronjones1Readme
@cycomdatasystems/headwindui
A React UI component library built with Tailwind CSS, Headless UI, and Motion. WCAG 2.1 AA compliant.
Install
npm install @cycomdatasystems/headwinduiPeer Dependencies
These packages are required and must be installed by the consuming application:
npm install react react-dom @headlessui/react @heroicons/react @tanstack/react-table motion tailwindcss| Package | Version | Used by |
|---------|---------|---------|
| react | >=18 | All components |
| react-dom | >=18 | All components |
| @headlessui/react | ^2.0 | Checkbox, Combobox, Drawer, Menu, Modal, Select, and others |
| @heroicons/react | ^2.0 | Banner, BottomSheet, Chip, Combobox, DatePicker, Drawer, Table |
| @tanstack/react-table | ^8.0 | Table |
| motion | >=11 | All animated components |
| tailwindcss | ^4.0 | All components (styling) |
Optional Peer Dependencies
These are only needed if you use the specific components listed:
# For HWDatePicker
npm install date-fns react-day-picker
# For HWToast / hwToast
npm install react-hot-toast| Package | Version | Used by |
|---------|---------|---------|
| date-fns | ^3.0 \|\| ^4.0 | DatePicker |
| react-day-picker | ^9.0 | DatePicker |
| react-hot-toast | ^2.4 | Toast |
Usage
import { HWButton, HWModal, hwToast } from "@cycomdatasystems/headwindui";
import "@cycomdatasystems/headwindui/styles.css";⚠️ The
styles.cssimport is required. It contains the@themedeclaration that registers everyhw-*design token (bg-hw-primary,text-hw-surface,text-hw-danger,rounded-hw-md,outline-hw-focus-ring, etc.) plus their.darkoverrides. Without it, every HW component renders unstyled — buttons have no background, inputs have no borders, required-field asterisks are invisible. Adding a Tailwind v4@sourcedirective pointing at the package does not substitute for this import:@sourceonly controls class-string scanning, it does not register design tokens.
Theming (light / dark / system)
Wrap your app in <HWThemeProvider> and drop <HWThemeToggle> wherever you want the switcher. The hook useTheme() exposes { mode, resolved, setMode }.
import { HWThemeProvider, HWThemeToggle } from "@cycomdatasystems/headwindui";
export function App() {
return (
<HWThemeProvider>
<HWThemeToggle />
{/* …rest of your app… */}
</HWThemeProvider>
);
}To prevent a flash of the wrong theme on first paint, inline this script in <head> before React mounts:
<script>
(function () {
try {
var s = localStorage.getItem('headwind_theme') || 'system';
var dark = s === 'dark' || (s === 'system' && matchMedia('(prefers-color-scheme: dark)').matches);
if (dark) document.documentElement.classList.add('dark');
document.documentElement.setAttribute('data-theme', s);
} catch (e) {}
})();
</script>For AI tooling
The full usage guide (AI_AGENT_GUIDE.md) and a compact component-selection manifest (COMPONENT_INDEX.yaml) ship inside the published package so AI coding agents running in a consuming app can read accurate, version-pinned guidance from node_modules without cloning this repo. Resolve them via the package's subpath exports:
require.resolve("@cycomdatasystems/headwindui/agent-guide"); // → dist/AI_AGENT_GUIDE.md
require.resolve("@cycomdatasystems/headwindui/manifest"); // → dist/manifest/COMPONENT_INDEX.yamlThe manifest is stamped with _packageVersion at the top so tools can detect when a cached copy has gone stale relative to the installed version.
Development
# Install dependencies
npm install
# Start Storybook
npm run storybook
# Run tests
npm test
# Build the library
npm run buildNaming Convention
All exported components use the HW prefix:
- Components:
HWButton,HWModal - Sub-components:
HWModal.Title,HWMenu.Item - Props:
HWButtonProps,HWModalProps - Imperative APIs:
hwToast.success()
License
MIT