---
name: humandify-project
description: Use when the user has an existing React project NOT created with humand-create-app and wants it adapted to Humand's visual standards. Works with any stack (MUI vanilla, Chakra, Tailwind, CSS). Automates dependency installation, Hugo theme setup, and code style configuration.
metadata:
  category: Project Creation
---

# Skill: Humandify an Existing Project

Adapts an external React project to the Humand stack: installs `material-hu` (Hugo theme), configures Vite and TypeScript with the correct aliases, applies theme and layer providers in the app entry point, and generates a report of what remains to migrate. The user only confirms at the start — the rest runs automatically.

## When to Use

- The user has a React project that was **not** created with `humand-create-app`
- They want to apply Humand's visual standards (colors, typography, components)
- Typical phrases: "aplicar el estilo de Humand", "el proyecto no tiene los colores de Humand", "adaptar al estándar de Humand"

**Do not use if:**
- `package.json` already has `material-hu` (already adapted)
- The project is not React

## Templates

All reference files live in the `templates/` folder inside this skill (check `Base directory for this skill:` in context for the exact path).

```
templates/
├── vite.config.ts          → replaces vite.config.ts if it doesn't exist
├── tsconfig.json           → replaces tsconfig.json if it doesn't exist
├── biome.jsonc             → always replaces biome.json / biome.jsonc
├── material-hu.d.ts        → src/types/material-hu.d.ts
├── App.snippet.tsx         → merge guide for the app entry point
└── scripts/dev.ts          → scripts/dev.ts (dev server on port 3000)
```

## Prerequisites

- `/setup-sandbox` has been run on this machine (token at `~/.humand/github-token`)
- The dev server is not running
- The project has `package.json` and is React

## Steps

### 1. Analyze the project

Read `package.json` and determine:

| Data | How to detect |
|------|--------------|
| Component library | `dependencies` in `package.json` |
| Has `vite.config.ts`? | File existence |
| Has `tsconfig.json`? | File existence |
| Has `biome.json` or `biome.jsonc`? | File existence |

Categorize the stack as one of:
- **MUI vanilla** — has `@mui/material` in `dependencies`
- **Other stack** — Chakra, Tailwind, plain CSS, another library, or none

### 2. Inform the user and ask for confirmation

> Analicé tu proyecto. Usa [stack detectado]. Voy a hacer lo siguiente:
>
> - Instalar las librerías de diseño de Humand
> - Aplicar el tema visual Hugo (colores, tipografías, componentes)
> - Configurar el linter de código de Humand
> - Configurar el servidor de desarrollo en el puerto estándar (3000)
> [If MUI vanilla] - Generar un listado de archivos con componentes que se podrían migrar a Humand en un paso siguiente
>
> No se borra ningún archivo existente.
>
> ¿Arrancamos?

**Wait for confirmation before continuing.**

### 3. Safety checkpoint

Initialize Git if not present, then commit:

```bash
git init --quiet 2>/dev/null; git add -A && git commit -m "checkpoint: before humandify"
```

Tell the user:

> Guardé el estado actual del proyecto. Si algo sale mal, podemos volver a este punto.

### 4. Configure .npmrc for Humand dependencies

Check that `~/.npmrc` has the private registry entry. If not:

```bash
echo "@humanddev:registry=https://npm.pkg.github.com" >> ~/.npmrc
echo "//npm.pkg.github.com/:_authToken=$(cat ~/.humand/github-token)" >> ~/.npmrc
```

### 5. Install Humand dependencies

```bash
bun add "material-hu@npm:@humanddev/material-hu@latest" "hu-translations@npm:@humanddev/hu-translations@latest"
bun add -D "@biomejs/biome@2.3.13" "humand-biome-config@npm:@humanddev/humand-biome-config@latest"
```

**If it fails with 401/403:**
1. Ask the user for a fresh GitHub token
2. Save it: `echo "<token>" > ~/.humand/github-token`
3. Update `_authToken` in `~/.npmrc` with the new token
4. Re-run the install commands

**If it fails for any other reason:** translate the error to plain Spanish and ask the user how to proceed. Do not attempt to fix manually.

### 6. Configure vite.config.ts

**If the file does not exist:** copy `templates/vite.config.ts` to the project root.

**If it already exists:** apply the following changes:

1. Add to the top of the file:
   ```ts
   import { getNodeModule } from 'material-hu/vite';
   ```

2. Add to the `resolve.alias` block (or create it if absent):
   ```ts
   '@material-hu/mui/lab': getNodeModule('@mui/lab'),
   '@material-hu/mui/x-date-pickers': getNodeModule('@mui/x-date-pickers'),
   '@material-hu/mui': getNodeModule('@mui/material'),
   '@material-hu/icons/material': getNodeModule('@mui/icons-material'),
   '@material-hu/icons/tabler': getNodeModule('@tabler/icons-react'),
   '@material-hu/hooks': getNodeModule('material-hu/lib/hooks'),
   '@material-hu/utils': getNodeModule('material-hu/lib/utils'),
   '@material-hu/types': getNodeModule('material-hu/lib/types'),
   '@material-hu/styles': getNodeModule('material-hu/lib/styles'),
   '@material-hu/theme': getNodeModule('material-hu/lib/theme'),
   '@material-hu/components': getNodeModule('material-hu/lib/components'),
   ```

Preserve all existing plugins and proxy entries from the original file.

### 7. Configure tsconfig.json

**If the file does not exist:** copy `templates/tsconfig.json` to the project root.

**If it already exists:** merge the following entries into `compilerOptions.paths` (do not replace existing paths):

```json
"@material-hu/components/*": ["node_modules/material-hu/lib/components/*"],
"@material-hu/mui/x-date-pickers/*": ["node_modules/@mui/x-date-pickers/*"],
"@material-hu/mui/x-date-pickers": ["node_modules/@mui/x-date-pickers"],
"@material-hu/mui/lab/*": ["node_modules/@mui/lab/*"],
"@material-hu/mui/lab": ["node_modules/@mui/lab"],
"@material-hu/mui/*": ["node_modules/@mui/material/*"],
"@material-hu/mui": ["node_modules/@mui/material"],
"@material-hu/icons/material/*": ["node_modules/@mui/icons-material/*"],
"@material-hu/icons/material": ["node_modules/@mui/icons-material"],
"@material-hu/hooks/*": ["node_modules/material-hu/lib/hooks/*"],
"@material-hu/utils/*": ["node_modules/material-hu/lib/utils/*"],
"@material-hu/types/*": ["node_modules/material-hu/lib/types/*"],
"@material-hu/styles/*": ["node_modules/material-hu/lib/styles/*"],
"@material-hu/theme/*": ["node_modules/material-hu/lib/theme/*"],
"@material-hu/icons/tabler": ["node_modules/@tabler/icons-react/dist/tabler-icons-react.d.ts"],
"material-hu/lib/*": ["node_modules/material-hu/lib/*"]
```

Also ensure `compilerOptions` has `"moduleResolution": "bundler"` — replace `"node"` if present.

### 8. Configure biome.jsonc

Copy `templates/biome.jsonc` to the project root (overwrite). Remove any old `biome.json`:

```bash
rm -f biome.json
```

### 9. Create TypeScript declarations

```bash
mkdir -p src/types
```

Copy `templates/material-hu.d.ts` → `src/types/material-hu.d.ts` (only if it does not already exist).

### 10. Apply Hugo theme in the app entry point

Find the app entry point (`src/App.tsx`, `src/app.tsx`, `App.tsx`, or similar).

Using `templates/App.snippet.tsx` as a guide, **add** the following to the existing file:

Imports (after existing imports):
```ts
import { ThemeProvider } from '@material-hu/mui/styles';
import { createHuGoTheme } from '@material-hu/theme/hugo';
import { DialogLayerProvider } from '@material-hu/components/layers/Dialogs';
import { DrawerLayerProvider } from '@material-hu/components/layers/Drawers';
import { MenuLayerProvider } from '@material-hu/components/layers/Menus';
```

Theme variable (inside the root component, before the `return`):
```ts
const theme = createHuGoTheme();
```

Wrap the existing `return` content with the providers:
```tsx
<ThemeProvider theme={theme}>
  <MenuLayerProvider>
    <DialogLayerProvider>
      <DrawerLayerProvider>
        {/* existing content — do not modify */}
      </DrawerLayerProvider>
    </DialogLayerProvider>
  </MenuLayerProvider>
</ThemeProvider>
```

**If the file already has a `ThemeProvider` from `@mui/material/styles`:** replace that import and instance with the material-hu versions above.

**Do not remove or move any existing content.**

### 11. Add the dev script for port 3000

Copy `templates/scripts/dev.ts` → `scripts/dev.ts`.

Add or update the `"dev"` script in `package.json`:
```json
"dev": "bun scripts/dev.ts"
```

If `concurrently` is not installed:
```bash
bun add -D concurrently
```

If `mock/db.json` does not exist, create it so `bun dev` does not crash:
```bash
mkdir -p mock
echo '{}' > mock/db.json
```

### 12. Verify

```bash
npx tsc --noEmit
bunx biome check --write ./src
```

Ignore `TS2688` and `TS5101`. Auto-fix incorrect import paths where resolvable. If there are logic errors that cannot be auto-fixed, note them for the report.

### 13. Report to the user

> **Tu proyecto ahora tiene el estilo visual de Humand.**
>
> Qué cambió:
> - Instaladas las librerías de diseño de Humand
> - Aplicado el tema visual Hugo (colores, tipografías)
> - Configurado el linter de código de Humand
> - Configurado el servidor de desarrollo en el puerto estándar (3000)
>
> [If MUI vanilla] Archivos con componentes MUI que funcionan con el tema pero se pueden migrar al sistema de componentes de Humand en un paso siguiente:
> [list of files containing `from '@mui/material'`]
>
> [If other stack] Los componentes de [Chakra/Tailwind/etc.] no heredan el tema de Humand automáticamente. Para un look completo habría que reemplazarlos por componentes de Humand en un paso siguiente.
>
> Siguiente paso: corrí `/start-project` para ver el proyecto en el navegador. Si querés documentarlo para gestionar features, seguí con `/document-project`.

## Error Recovery

| Error | Action |
|-------|--------|
| `401/403` on `bun add` | Fresh GitHub token → `echo "<token>" > ~/.humand/github-token` → re-run |
| Other `bun add` failure | Translate error to plain Spanish, do not fix manually |
| TypeScript logic errors post-migration | Note in report, do not block the skill |
| App won't open in browser | Do not diagnose — suggest http://localhost:3000 or contact a developer |
