@lexydesign/create-app

CLI oficial de Lexy para generar proyectos React + Vite + TypeScript con arquitectura estandarizada, addons opcionales (Tailwind, shadcn, React Router…), el sistema de diseño Lexy vía @lexydesign/react y un registry de componentes listo para eject/customización avanzada.

mkdir mi-app && cd mi-app
npx @lexydesign/create-app

Contenido

• ¿Qué hace?
• Inicio rápido
• Crear un proyecto (create)
  • Modo interactivo
  • Modo automatizado (headless)
• Arquitecturas
• Addons
• El archivo .lexy
• Agregar elementos (add)
• Catálogo de componentes
• Sistema de diseño (tema)
• Infraestructura de IA del template
• Desarrollo del CLI (contribuir a este repo)
  • Estructura del repositorio
  • Sincronizar @lexydesign/react
  • Storybook
  • Probar el CLI en local
  • Publicar una versión
  • Publicar @lexydesign/react

¿Qué hace?

El CLI cubre cuatro funciones:

| Función | Comando | Resultado | |---|---|---| | Crear un proyecto | create-lexy | Scaffold completo de React + Vite + TS con la arquitectura, addons y @lexydesign/react instalados. | | Ejectar elementos | create-lexy add <Nombre> --component | Copia un componente, hook o servicio del registry al proyecto para customización avanzada. | | Diagnosticar el proyecto | create-lexy doctor | Valida (solo lectura) .lexy y la capa de IA; útil para CI. | | Diseñar con tokens | (incluido en el scaffold) | Tema Lexy unificado + catálogo de componentes documentado en Storybook. |

Inicio rápido

[!IMPORTANT] El scaffold se genera en el directorio actual (in-place), no en una subcarpeta. Crea una carpeta vacía, entra en ella y ejecuta el comando ahí. Si el directorio ya contiene package.json, src, index.html o .lexy, el CLI aborta para no sobrescribir un proyecto existente.

mkdir mi-app && cd mi-app
npx @lexydesign/create-app

También funcionan los atajos create de cada gestor, que resuelven internamente al mismo paquete:

npm create @lexydesign/app
# o
pnpm create @lexydesign/app

El nombre publicado es @lexydesign/create-app. El atajo create @lexydesign/app es azúcar que npm/pnpm expanden a ese paquete. Si ves una versión vieja en caché, fuerza la última con npx @lexydesign/create-app@latest.

Al terminar, el proyecto queda listo en el directorio actual. Siguiente paso:

pnpm dev

Crear un proyecto (create)

create es el comando por defecto: create-lexy, create-lexy create y create-lexy init son equivalentes.

Modo interactivo

Te guía por nombre, configuración y addons:

create-lexy

Ofrece dos caminos:

• Configuración recomendada — arquitectura feature + todos los addons (Tailwind, React Router, Lucide, shadcn, React Compiler, React Doctor, GitHub Actions y Husky).
• Personalizar — eliges arquitectura y addons manualmente.

Modo automatizado (headless)

Útil para scripts y agentes. Se activa solo cuando pasas el nombre del proyecto y --type a la vez:

create-lexy create mi-app --type feature --addons tailwind,shadcn,react-router

| Argumento / opción | Descripción | |---|---| | mi-app | Nombre del proyecto (queda en package.json). No crea una carpeta con ese nombre; el scaffold es in-place. | | -t, --type <arch> | Arquitectura: feature o layer. Obligatorio en headless; si lo omites, el CLI entra en modo interactivo. | | -a, --addons <lista> | Addons separados por coma. Los valores inválidos se ignoran. | | -w, --world <mundo> | Mundo de diseño: cliente, crm o mixto. Opcional; se guarda en .lexy como default para los agentes. Si lo omites, el campo no se escribe. |

Seleccionar shadcn añade automáticamente tailwind y lucide-react.

Arquitecturas

El CLI genera una de dos estructuras de carpetas según --type:

feature — recomendada para apps escalables

src/
├── app/                  # Entrada, layout y router
├── features/             # Módulos por funcionalidad
└── shared/
    ├── assets/
    ├── components/
    │   └── base/         # ← destino de `add --component`
    ├── hooks/            # ← destino de `add --hook`
    ├── services/         # ← destino de `add --service`
    ├── lib/              # cn.ts y utilidades
    └── types/

layer — clásica, por capas

src/
├── assets/
├── components/
│   └── base/             # ← destino de `add --component`
├── hooks/                # ← destino de `add --hook`
├── services/             # ← destino de `add --service`
├── lib/                  # cn.ts y utilidades
├── types/
├── views/
└── stores/

Las rutas concretas de cada arquitectura quedan registradas en .lexy y son las que usa add para saber dónde copiar.

Addons

Todos son opcionales y se instalan solo si los seleccionas (opt-in), manteniendo el bootstrap mínimo.

| Addon | Qué configura | |---|---| | tailwind | TailwindCSS v4 vía @tailwindcss/vite, helper cn, e index.css con el tema Lexy. | | shadcn | components.json (estilo new-york). Implica tailwind + lucide-react. | | lucide-react | Librería de íconos. | | react-router | react-router-dom + Router.tsx base y carpeta de middlewares. | | react-compiler | Cambia a @vitejs/plugin-react y activa babel-plugin-react-compiler. | | react-doctor | Script doctor de análisis en package.json. | | github-actions | Workflow ci.yml (install → lint → build). | | husky | git init + Husky + lint-staged con hook pre-commit. |

El archivo .lexy

Cada proyecto generado incluye un .lexy en la raíz: es el manifiesto que el comando add lee para saber arquitectura y rutas de destino.

{
  "version": "1.0.0",
  "generatedAt": "2026-06-08T00:00:00.000Z",
  "architecture": "feature",
  "world": "cliente",
  "addons": ["tailwind", "shadcn", "react-router"],
  "paths": {
    "components": "src/shared/components/base",
    "hooks": "src/shared/hooks",
    "services": "src/shared/services",
    "lib": "src/shared/lib",
    "views": "src/features"
  }
}

world (cliente, crm o mixto) es opcional: lo capturas al crear el proyecto (prompt interactivo o --world) y los agentes de diseño lo leen como default para orientar densidad, voz y elección de componentes. Si no se definió, el campo simplemente no aparece y el agente preguntará.

Agregar elementos (add)

Los componentes se usan desde @lexydesign/react por defecto:

import { Button } from "@lexydesign/react";

El comando add es la vía de eject: copia un elemento del registry al proyecto actual cuando necesitas editar algo que la librería no expone, como estructura DOM interna, lógica, defaults, variantes no disponibles o dependencias internas. Debe ejecutarse en la raíz de un proyecto generado (donde está el .lexy).

create-lexy add Button --component     # eject de componente
create-lexy add useAuth  --hook        # hook
create-lexy add authApi  --service     # servicio

| Opción | Destino (según .lexy) | |---|---| | -c, --component | paths.components | | -k, --hook | paths.hooks | | -s, --service | paths.services |

Al ejectar un componente, el CLI automáticamente:

• Crea cn.ts en paths.lib si no existe.
• Instala las dependencias base (clsx, tailwind-merge).
• Instala class-variance-authority si el componente lo usa.
• Instala las dependencias externas específicas (Radix, cmdk, lucide-react…) solo de los componentes que las importan.
• Resuelve y copia dependencias internas transitivas. Por ejemplo:
  • Combobox → copia Popover, Command y Button.
  • Sidebar → copia Sheet, Button, Input, Separator, Skeleton y Tooltip.
• Copia los assets asociados. Por ejemplo, Logo copia assets/logo.

Un componente ejectado deja de recibir upgrades automáticos de @lexydesign/react: pasa a ser código local del proyecto.

Diagnosticar el proyecto (doctor)

Comando de solo lectura que valida la integridad del proyecto generado. No modifica ni instala nada, así que es seguro de correr en CI.

create-lexy doctor

Verifica, en orden:

• .lexy existe y es JSON válido (con version, architecture, addons, paths.components y world válido si está presente).
• La carpeta de componentes (paths.components) existe.
• La capa de IA está completa (AGENTS.md, CLAUDE.md, ambos SKILL.md, ai/PROJECT-CONTEXT.md, ai/lexy-ai-manifest.json, .github/copilot-instructions.md y las 8 pautas) y el manifest es JSON válido.
• El manifest no driftó respecto a la librería instalada: compara su sección components con node_modules/@lexydesign/react/src/components y avisa si difieren (aviso, no error).

Sobre la capa de IA removible: si retiraste todos los marcadores (AGENTS.md, CLAUDE.md, .claude/, ai/) antes de producción, doctor lo informa como aviso y termina OK. Si solo falta una parte, lo marca como error (probable borrado accidental).

Exit codes: 0 si todo está bien o la capa de IA fue retirada por completo; 1 si falta o está corrupto .lexy, o si hay cualquier ✗.

Catálogo de componentes

Los componentes viven en templates/elements/components y están documentados en Storybook (ver Storybook). Organizados por categoría:

| Categoría | Componentes | |---|---| | Navegación | AppHeaderBar, AppSidebar, Breadcrumb, HeaderBar, Menubar, NavigationMenu, Pagination | | Formularios | Button, Checkbox, Combobox, Input, Label, RadioGroup, Searchbox, Select, Slider, Switch, Textarea | | Feedback | Badge, CounterBadge, Progress, Skeleton, StatusDot, Toast, Tooltip | | Overlays | Command, Dialog, DropdownMenu, Popover | | Datos | Accordion, Card, Separator, Snippet, Table, Tabs, Tag, Tree | | Identidad | Avatar, FeatureCard, Logo, ProfileCard |

Para el layout completo de una app interna (sidebar colapsable + área de trabajo) compón SidebarProvider + AppSidebar + SidebarInset (ver AppSidebar.md).

[!TIP] AppSidebar es la barra de navegación. Recibe groups, user, logo y logoIcon como datos y compone la sidebar correctamente (data-driven), lo que evita errores al generar la UI con un agente de IA. Sidebar y Sheet son primitivas internas que AppSidebar usa por debajo (se copian como dependencia); recurre a ellas solo para casos a medida. Al agregar AppSidebar con add, se copia junto a él un AppSidebar.md con la guía de uso para que un agente lo consulte en el proyecto.

Sistema de diseño (tema)

La fuente única de verdad del tema es templates/lexy-theme.css. Lo consumen tanto Storybook como el proyecto generado, así que cualquier cambio de tokens se hace ahí.

• Tipografía: Noto Sans (variable, auto-hospedada, SIL OFL) como fuente única. El woff2 vive en public/fonts (Storybook) y se propaga a templates/base/public/fonts (proyecto generado).
• Color: tokens semánticos con nomenclatura shadcn/Tailwind (bg-primary, text-muted-foreground…) y valores alineados con LexyDesign. Cada token trae su contraste *-foreground; los fondos de estado se aplican por opacidad (bg-success/10…).
• Escala tipográfica: rampa text-xs … text-5xl, con tracking nativo en cuerpo y negativo progresivo en titulares.
• Espaciado: tokens semánticos (stack-sm/md/lg, gutter, section-gap, page-bottom, margin-mobile/desktop, container-max).

Las stories Estilo/Color y Estilo/Tipografía documentan estos tokens de forma visual.

Infraestructura de IA del template

Los proyectos generados incluyen una infraestructura de IA removible que guía a agentes (Claude Code, Copilot, etc.) para implementar interfaces usando el registry y el sistema de diseño.

| Archivo | Propósito | |---|---| | AGENTS.md | Entrada principal para agentes: marca, regla de ruteo y mapa de carga de contexto. | | CLAUDE.md | Entrada automática para Claude Code (router corto hacia AGENTS.md). | | .github/copilot-instructions.md | Entrada automática para GitHub Copilot (router corto). | | .claude/skills/lexy-design/SKILL.md | Skill de diseño: proceso de cinco fases con puertas. | | .claude/skills/lexy-dev/SKILL.md | Skill técnica para asistir a un diseñador no-coder. | | ai/README.md | Índice de la infraestructura. | | ai/PROJECT-CONTEXT.md | Brief vivo del proyecto: objetivo, audiencia, referencias y decisiones. El scaffold lo sella con nombre, mundo y fecha; los agentes lo mantienen. | | ai/IMPLEMENTATION-PROTOCOL.md | Protocolo obligatorio para implementar interfaces. | | ai/lexy-ai-manifest.json | Índice JSON de comandos, rutas, addons y componentes. La sección components se genera con pnpm sync:manifest desde el registry. | | ai/TECHNICAL-USAGE.md | Guía técnica para usar el template e importar componentes. | | ai/pautas/diseno-cliente.md | Pautas para interfaces de cliente. | | ai/pautas/diseno-crm-lexy.md | Pautas para CRM e interfaces internas. | | ai/pautas/sistema-visual.md | Densidad, espaciado, estados, tipografía y motion. | | ai/pautas/recetas-layout.md | Composiciones canónicas en código. | | ai/pautas/buenas-practicas.md | Elección de componentes, estados y anti-patrones. | | ai/pautas/arquitectura-informacion-ux.md | Jerarquía, progressive disclosure, carga visual. | | ai/pautas/ux-writing.md | UX writing y microcopy. | | ai/pautas/calidad-industria.md | Vara de calidad: señales de UI genérica y pase final anti-slop. | | ai/PRODUCTION-CLEANUP.md | Comando para retirar todo antes de producción. |

La sincronización registry → librería → manifest se valida con docs/vibe-coding-eval.md (protocolo de evaluación con agentes reales) y con create-lexy doctor en el proyecto generado.

Para eliminar la infraestructura antes de producción, el proyecto generado trae ai/PRODUCTION-CLEANUP.md con el comando exacto y la verificación de referencias residuales (el comando vive solo ahí para evitar copias drifteadas).

Desarrollo del CLI (contribuir a este repo)

Esta sección es para quien trabaja en el propio CLI, no para quien lo usa.

Estructura del repositorio

.
├── src/                      # Código del CLI (TypeScript)
│   ├── index.ts              # Entrada y definición de comandos (commander)
│   ├── commands/add.ts       # Comando `add` + registry de dependencias
│   ├── prompts/              # Prompts interactivos (@clack/prompts)
│   ├── services/             # scaffold.ts e installAddons.ts
│   └── types/
├── templates/
│   ├── base/                 # Plantilla del proyecto generado
│   ├── elements/components/  # Registry de componentes copiables
│   └── lexy-theme.css        # Tema (fuente única de verdad)
├── packages/react/           # Librería @lexydesign/react generada desde el registry
├── stories/                  # Storybook (consume templates/elements)
├── scripts/generate-react-library.ts # Sincroniza registry → packages/react
├── scripts/release-react.sh  # Publicación de @lexydesign/react
├── scripts/release.sh        # Publicación a npm
└── dist/                     # Build del CLI (tsup) — se publica

El paquete publicado solo incluye dist y templates (campo files). El código de src, stories y scripts no se publica.

Sincronizar @lexydesign/react

@lexydesign/react y el manifest de IA se generan desde el registry local:

templates/elements/components
  → packages/react/src/components            (librería)
  → templates/base/ai/lexy-ai-manifest.json  (sección components del manifest)

Después de modificar componentes o sus .md companion en templates/elements/components, sincroniza librería y manifest con:

pnpm sync:react

Para regenerar solo la sección components del manifest de IA (scripts/generate-ai-manifest.ts deriva exports y dependencias del código fuente; las variantes y descripciones curadas viven en el mapa EXTRAS del script):

pnpm sync:manifest

Para sincronizar y compilar el paquete React en un solo paso:

pnpm build:react

Ese comando ejecuta:

pnpm sync:react
pnpm --dir packages/react build

La librería generada mantiene cada componente y su documentación juntos:

packages/react/src/components/Button/
├── Button.tsx
├── Button.md
└── index.ts

Para validar el contenido publicable sin publicar:

cd packages/react
npm pack --dry-run

Modelo de consumo:

• Library-first: las apps generadas importan desde @lexydesign/react.
• Registry-second: create-lexy add <Componente> --component solo ejecta una copia editable.
• Source canónico: los cambios de componentes se hacen en templates/elements/components y luego se sincronizan con pnpm sync:react (librería + manifest de IA).

Storybook

Storybook vive en la raíz y permite ver y trabajar los componentes de templates/elements/components sin tocar la plantilla ni un proyecto generado.

pnpm install
pnpm storybook          # http://localhost:6006
pnpm build-storybook    # versión estática en storybook-static/ (ignorada por Git)

Detalles:

• Framework @storybook/react-vite 8.6.18.
• Historias en stories/**/*.stories.tsx.
• Alias @ → ./src; CSS base en src/styles/storybook.css; tema compartido en templates/lexy-theme.css.

Probar el CLI en local

1. Construir y linkear globalmente este CLI (en este repo):

   pnpm run local:setup

2. Enlazarlo en tu proyecto de prueba:

   pnpm link --global @lexydesign/create-app

3. Probarlo:

   create-lexy

Tras cada cambio en el CLI, reconstruye y vuelve a linkear:

pnpm run local:refresh

Para limpiar los enlaces — en este repo pnpm run local:unlink; en el proyecto de prueba pnpm unlink @lexydesign/create-app.

Publicar una versión

La publicación está automatizada en scripts/release.sh (atajo pnpm release). El script:

1. Carga NPM_TOKEN desde .env (token de automatización de npm, salta el 2FA).
2. Sube la versión en package.json según el tipo de bump.
3. Verifica que la versión resultante no coincida con la ya publicada (aborta si sí).
4. Construye el dist.
5. Publica con un .npmrc temporal, sin tocar tu ~/.npmrc.

pnpm release            # bump patch (1.0.x → 1.0.x+1) y publica
pnpm release minor      # bump minor
pnpm release major      # bump major
pnpm release --no-bump  # publica la versión ya escrita en package.json

Publicar @lexydesign/react

La librería React se genera desde el registry local y se publica como paquete npm separado. El flujo está automatizado en scripts/release-react.sh (atajo pnpm release:react).

El script:

1. Carga NPM_TOKEN desde .env.
2. Regenera packages/react desde templates/elements/components.
3. Sube la versión de packages/react/package.json según el bump indicado.
4. Construye dist con tsup.
5. Ejecuta npm pack --dry-run.
6. Publica @lexydesign/react con un .npmrc temporal.
7. Verifica la versión publicada con npm view.

pnpm release:react            # bump patch y publica @lexydesign/react
pnpm release:react minor      # bump minor
pnpm release:react major      # bump major
pnpm release:react --no-bump  # usa la versión local; si ya existe, hace patch automático

Para validar sin publicar:

pnpm build:react
cd packages/react
npm pack --dry-run

[!IMPORTANT] Copia .env.example a .env y coloca tu NPM_TOKEN. El .env está en .gitignore y nunca se incluye en el paquete.