open-index/open-npm huggingface dataset:
npm package: @josui/cli
Description: CLI tools for josui
Latest version: 0.2.0

# @josui/cli

CLI tools and Vite plugin for local development with josui packages.

## Installation

```bash
pnpm add -D @josui/cli
```

## Vite Plugin

Resolve `@josui/*` imports to local source during development. Add to your `vite.config.ts`:

```ts
import { josuiDev } from "@josui/cli/vite";

export default defineConfig({
  plugins: [josuiDev()],
});
```

The plugin auto-discovers all packages in your local josui repo and creates Vite aliases so imports resolve to the raw TypeScript source. This gives you HMR and avoids the symlink/node_modules pitfalls.

It also configures `resolve.dedupe` (React singleton), `server.fs.allow`, `optimizeDeps.exclude`, and `ssr.noExternal` automatically.

### Path resolution

The plugin finds your josui repo in this order:

1. **Param**: `josuiDev({ josuiPath: '../josui' })`
2. **Config file**: `josuiPath` in `.josui.json`
3. **Default**: `../josui`

If the path doesn't exist, the plugin silently disables itself (safe for CI/production).

## CLI

### Link skills

Symlink Claude Code skills from josui packages into your project:

```bash
npx josui link skills
```

Creates symlinks in `.claude/skills/` pointing to skill directories in josui packages. Re-running removes deprecated skills and re-links the current selection.

### Running from source

```bash
node <path-to-josui>/packages/cli/dist/index.mjs link skills
```

## Configuration

Settings are saved to `.josui.json` (add to `.gitignore`):

```json
{
  "josuiPath": "../josui",
  "linkedSkills": [{ "source": "react", "skills": ["use-react-components"] }]
}
```
npm package: @josui/core
Description: Pure JavaScript utilities for the Josui design system. Works anywhere — Node.js, browser, SSR.
Latest version: 0.2.1

# @josui/core

Pure JavaScript utilities for the Josui design system. Works anywhere — Node.js, browser, SSR.

## Installation

```bash
pnpm add @josui/core
```

## Usage

```ts
import { toRgb, toHex, parse } from "@josui/core";

// Convert to RGB
toRgb("#ff0000"); // "rgb(255, 0, 0)"
toRgb("oklch(0.6 0.15 30)"); // "rgb(219, 98, 89)"

// Convert to hex
toHex("rgb(255, 0, 0)"); // "#ff0000"

// Full culori parse (for advanced use)
parse("oklch(0.6 0.15 30)"); // { mode: 'oklch', l: 0.6, c: 0.15, h: 30 }
```

## Utilities

- **Color** — `toRgb`, `toHex`, `parse`, `formatRgb`, `formatHex`

Powered by [culori](https://culorijs.org/).
npm package: @josui/core-web
Description: Shared web utilities for the Josui design system. Framework-agnostic helpers for DOM, canvas, cursors, and more.
Latest version: 0.2.1

# @josui/core-web

Shared web utilities for the Josui design system. Framework-agnostic helpers for DOM, canvas, cursors, and more.

## Installation

```bash
pnpm add @josui/core-web
```

## Usage

```ts
import { cn, createCustomCursor, createCellGridController } from "@josui/core-web";

// Merge Tailwind classes with proper precedence
const className = cn("px-4 py-2", isActive && "bg-blue-500", className);

// Create a custom cursor
const cursor = createCustomCursor(element, { interactiveScale: 2.5 });

// Create an interactive cell grid
const controller = createCellGridController(canvas, { cellSize: 24 });
controller.start();
```

## Utilities

- **cn** — Merge Tailwind CSS classes with `clsx` + `tailwind-merge`
- **createCustomCursor** — GSAP-powered custom cursor with interactive element detection
- **createCellGridController** — Interactive canvas cell grid that follows cursor movement
- **interactiveState** — Pub/sub state for tracking cursor over interactive elements
- **isInteractiveElement** — Check if an element is interactive (button, link, etc.)
- **isTouchDevice** — Detect touch-capable devices
- **getCssVariable** — Retrieve CSS variable values from the DOM
- **resolveColor** — Resolve color tokens (e.g., `color-primary-500`) to CSS variable values
- **themeState** — Theme manager singleton (light/dark/system) with localStorage persistence
- **getThemeScript** — Blocking script to prevent theme flash on SSR
- **createKeyboardShortcut** — Keyboard shortcut listener with cleanup
- **parseShortcut** — Parse shortcut strings (e.g., "ctrl+shift+t") into objects
npm package: @josui/eslint-config
Description: Shared ESLint flat configs for josui projects.
Latest version: 0.2.0

# @josui/eslint-config

Shared ESLint flat configs for josui projects.

## Installation

```bash
pnpm add -D @josui/eslint-config eslint
```

## Configs

- `@josui/eslint-config` — Base TypeScript config
- `@josui/eslint-config/react` — React + TypeScript

## Usage

```ts
// eslint.config.ts
import { createReactConfig } from '@josui/eslint-config/react';

export default createReactConfig(import.meta.dirname);
```

```ts
// eslint.config.ts
import { createConfig } from '@josui/eslint-config';

export default createConfig(import.meta.dirname);
```
npm package: @josui/prettier-config
Description: Shared Prettier configuration for josui projects.
Latest version: 0.2.0

# @josui/prettier-config

Shared Prettier configuration for josui projects.

## Installation

```bash
pnpm add -D @josui/prettier-config prettier
```

## Usage

In `package.json`:

```json
{
  "prettier": "@josui/prettier-config"
}
```

With Tailwind CSS (includes automatic class sorting):

```json
{
  "prettier": "@josui/prettier-config/tailwind"
}
```
npm package: @josui/react
Description: React component library for the Josui design system.
Latest version: 0.5.0

# @josui/react

React component library for the Josui design system.

## Installation

```bash
pnpm add @josui/react
```

## Setup

### 1. Import Tailwind styles

```css
/* app.css or globals.css */
@import "@josui/tailwind";
```

### 2. Configure Tailwind source scanning

Add the `@source` directive to your CSS to ensure Tailwind scans the component library for class names:

```css
/* app.css or globals.css */
@import "@josui/tailwind";
@source '../node_modules/@josui/react/src';
```

This tells Tailwind v4 to include the component library's source folder when scanning for utility classes. Without this, component styles may be purged from your production build.

## Architecture

### Tailwind CSS Styling

Components use Tailwind CSS classes with the `cn()` utility from `@josui/core-web` for class merging. All components support the `className` prop for customization:

```tsx
<Button className="my-custom-class" variant="primary">
  Click me
</Button>
```

### Accessibility

Components follow WAI-ARIA patterns with proper roles, labels, and keyboard navigation.

## Customizing Styles

### Override with className

All components accept a `className` prop that merges with default styles:

```tsx
<Button className="rounded-full" variant="primary">
  Rounded Button
</Button>
```

### Tailwind Configuration

Extend your Tailwind config to customize the design tokens:

```js
// tailwind.config.js
export default {
  theme: {
    extend: {
      colors: {
        primary: {
          500: "#your-color",
          600: "#your-hover-color",
        },
      },
    },
  },
};
```

## Components

- **Button** — Primary actions with variants, sizes, loading state
- **Card** — Container with header, content, footer sections
- **Input** — Form input field
- **Badge** — Status indicators and labels
- **Typography** — Text styling component
- **Avatar** — User profile images
- **Spinner** — Loading indicator
- **Alert** — Notification messages
- **CustomCursor** — GSAP-powered custom cursor (auto-hidden on touch)
- **CellGrid** — Interactive canvas background with cell highlighting
- **ThemeToggle** — Dark/light/system theme toggle button

## Hooks

- **useIsTouchDevice** — Detect touch-capable devices
- **useInteractiveState** — Subscribe to cursor over interactive element state
- **useScrollDirection** — Track scroll direction (up/down)
- **useTheme** — Manage theme state (light/dark/system) with optional keyboard shortcut
- **useKeyboardShortcut** — Add keyboard shortcuts with auto-cleanup

## AI-Assisted Development

This package includes a skill for AI coding assistants. Copy it to your project:

```bash
cp -r node_modules/@josui/react/skills/use-react-components .claude/skills/
```

The skill helps AI assistants correctly use components with proper props and patterns.

See Storybook for interactive examples and full API documentation.
npm package: @josui/tailwind-preset
Description: Shared Tailwind CSS v4 configuration for Josui components.
Latest version: 1.0.1

# @josui/tailwind-preset

Shared Tailwind CSS v4 configuration for Josui components.

## Installation

```bash
pnpm add @josui/tailwind-preset
```

## Usage

Import in your CSS entry point:

```css
@import "@josui/tailwind";
```

This provides Tailwind CSS v4, design tokens, and sensible body defaults.
npm package: @josui/token-studio
Description: Local CRUD editor for DTCG token category files.
Latest version: 0.2.2

# @josui/token-studio

Local CRUD editor for DTCG token category files.

See architecture and roadmap: `ARCHITECTURE.md`.

## Usage

### In this monorepo (development)

```bash
pnpm --filter @josui/token-studio build
pnpm --filter @josui/token-studio exec josui-token-studio
```

### In any project (installed package consumer)

Install:

```bash
npm install -D @josui/token-studio
```

Run:

```bash
npx josui-token-studio
# or
npm exec josui-token-studio
# or
pnpm exec josui-token-studio
```

Global install is also supported:

```bash
npm install -g @josui/token-studio
josui-token-studio
```

### CLI options

- `--cwd <path>`: project root (defaults to current directory)
- `--config <path>`: explicit config file path
- `--tokens-dir <path>`: override token category folder
- `--port <number>`: local server port
- `--no-open`: do not open browser automatically

## Config File

Token Studio auto-discovers a config file by walking upward from the current directory:

- `token-studio.config.json`
- `.token-studio.json`

Example:

```json
{
  "tokensDir": "packages/tokens/src/tokens",
  "terrazzoPath": "packages/tokens/terrazzo.config.mjs"
}
```

Create this file at your project root (or pass `--config <path>`).

`--tokens-dir` still takes precedence over config values.

## Routes

- `/categories`
- `/categories/$name`
- `/changes`
- `/settings`
npm package: @josui/typescript-config
Description: Shared TypeScript configurations for josui projects.
Latest version: 0.2.1

# @josui/typescript-config

Shared TypeScript configurations for josui projects.

## Installation

```bash
pnpm add -D @josui/typescript-config
```

## Configs

- `base.json` — Shared strict settings
- `browser.json` — Browser/bundler projects (DOM libs)
- `node.json` — Node.js projects (NodeNext)
- `react.json` — React projects (extends browser)

## Usage

```json
{
  "extends": "@josui/typescript-config/react.json"
}
```

```json
{
  "extends": "@josui/typescript-config/node.json"
}
```