@cycomdatasystems/headwindui

A React UI component library built with Tailwind CSS, Headless UI, and Motion. WCAG 2.1 AA compliant.

Install

npm install @cycomdatasystems/headwindui

Peer 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

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

Usage

import { HWButton, HWModal, hwToast } from "@cycomdatasystems/headwindui";
import "@cycomdatasystems/headwindui/styles.css";

⚠️ The styles.css import is required. It contains the @theme declaration that registers every hw-* design token (bg-hw-primary, text-hw-surface, text-hw-danger, rounded-hw-md, outline-hw-focus-ring, etc.) plus their .dark overrides. Without it, every HW component renders unstyled — buttons have no background, inputs have no borders, required-field asterisks are invisible. Adding a Tailwind v4 @source directive pointing at the package does not substitute for this import: @source only 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.yaml

The 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 build

Naming 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