# @neuctra/ui A React component library built with Tailwind CSS v4 and TypeScript: 76 exported components and subcomponents across forms, layout, data display, overlays, navigation, and feedback, all styled through a single semantic color-token system so an app's light and dark theme apply automatically without per-component work. This document explains the whole package: what it ships, how theming works underneath, every category of component, the machine-readable registry it includes, and how to set it up and troubleshoot it. --- ## 1. What this package is `@neuctra/ui` is a compiled, tree-shakeable component library. You install it, style your project's CSS with a small set of theme variables (once, manually or via the companion CLI), and import components the same way you would from any other library: ```tsx import { Button, Input } from "@neuctra/ui"; ``` Every component ships as compiled JavaScript (ESM and CommonJS) plus `.d.ts` type declarations, so it works in a plain Vite/CRA app, in Next.js (App Router or Pages Router), and with either `import` or `require`. The library does not ship a fixed color palette baked into components. Instead, every component reads CSS custom properties (`--primary`, `--background`, `--border`, and so on) through Tailwind classes like `bg-primary` or `text-foreground`. You define those variables once for your project, and every component in the library automatically matches — including your own custom components, if you use the same classes. --- ## 2. Installation ```bash npm install @neuctra/ui ``` ```bash yarn add @neuctra/ui ``` ```bash pnpm add @neuctra/ui ``` Tailwind CSS must be installed in your project separately — this package supplies components and a small stylesheet of keyframe animations, not a Tailwind installation. --- ## 3. Fastest setup: the CLI The companion package `@neuctra/ui-cli` generates the entire theme stylesheet described in section 4 for you, so you do not have to copy CSS by hand: ```bash npx @neuctra/ui-cli ``` It writes the token definitions, the `@theme` mapping, and the `@custom-variant dark` declaration into your project's CSS file, wraps your app root so `ThemeToggleButton` works out of the box, and confirms Tailwind is scanning `node_modules/@neuctra/ui`. Run this first on a new project, then skip straight to section 5 (Usage). If you would rather understand and control every line of the generated CSS yourself, continue reading section 4 and copy it manually. --- ## 4. Tailwind configuration ### Tailwind v4 ```css @import "tailwindcss"; @source "../node_modules/@neuctra/ui"; ``` `@source` is what makes Tailwind's v4 JIT scanner look inside the library's compiled output for class names to generate. Without it, classes used only inside `@neuctra/ui` components (not in your own source) will not exist in your final CSS. ### Tailwind v3 ```js export default { content: [ "./index.html", "./src/**/*.{js,ts,jsx,tsx}", "./node_modules/@neuctra/ui/**/*.{js,ts,jsx,tsx}", ], }; ``` Same purpose as `@source` above, expressed the v3 way. --- ## 5. Usage ```tsx import { Button, Dropdown, Input } from "@neuctra/ui"; export default function App() { return (
); } ``` Every component accepts a `className`, and consumer `className` always wins over the component's internal defaults (the library merges classes with `tailwind-merge` internally, so `