nave-ui-icons 0.1.0

package/README.md

@@ -0,0 +1,174 @@
+# nave-ui-icons
+
+Libreria de iconos React para el Design System de Nave.
+
+La libreria se penso para resolver tres cosas:
+
+- centralizar los iconos del sistema en un solo paquete
+- exponer una API estable para apps y librerias
+- evitar que cada proyecto importe SVGs sueltos o dependa de una implementacion distinta
+
+## Que contiene
+
+`nave-ui-icons` expone dos consumos principales:
+
+- `nave-ui-icons`
+  Usa iconos estaticos tipo Lucide.
+- `nave-ui-icons/icons`
+  Usa los iconos Nebula del Design System.
+
+Para el sistema de producto, el import recomendado es `nave-ui-icons/icons`.
+
+## Como se creo la libreria
+
+La libreria se armo como un paquete independiente dentro de `packages/ui-icons`.
+
+El flujo fue este:
+
+1. Se creo un paquete React separado para que los iconos no vivan mezclados con `ui-library`.
+2. Se definio una API unica para los iconos del sistema: `NebulaIcon`.
+3. Se tomaron como fuente los iconos de `icons.xml` y los SVGs agregados en `src/figma`.
+4. Se genero un catalogo tipado para poder buscar, documentar y renderizar iconos de forma consistente.
+5. Se dejo el paquete con build ESM, CJS y tipos para poder publicarlo o moverlo a otro proyecto.
+
+Archivos clave:
+
+- `packages/ui-icons/package.json`
+- `packages/ui-icons/tsup.config.ts`
+- `packages/ui-icons/src/icons.ts`
+- `packages/ui-icons/src/figma/index.tsx`
+- `packages/ui-icons/src/catalog.ts`
+
+## Instalacion
+
+### Opcion A: paquete publicado
+
+```bash
+npm install nave-ui-icons
+```
+
+### Opcion B: consumo local dentro de un monorepo
+
+En el `package.json` del proyecto consumidor:
+
+```json
+{
+  "dependencies": {
+    "nave-ui-icons": "file:../ui-icons"
+  }
+}
+```
+
+Despues:
+
+```bash
+npm install
+```
+
+## Como importarla
+
+### Import recomendado para iconos del Design System
+
+```tsx
+import { NebulaIcon } from 'nave-ui-icons/icons';
+```
+
+### Import recomendado si el nombre viaja por props
+
+```tsx
+import { NebulaIcon, type NebulaIconName } from 'nave-ui-icons/icons';
+```
+
+### Import de iconos estaticos tipo Lucide
+
+```tsx
+import { SearchIcon, ChevronRightIcon } from 'nave-ui-icons';
+```
+
+## Como usarla
+
+### Caso simple
+
+```tsx
+import { NebulaIcon } from 'nave-ui-icons/icons';
+
+export function SearchButton() {
+  return (
+    <button className="inline-flex items-center gap-2">
+      Buscar
+      <NebulaIcon name="Search" size={18} />
+    </button>
+  );
+}
+```
+
+### Caso con props tipadas
+
+```tsx
+import { NebulaIcon, type NebulaIconName } from 'nave-ui-icons/icons';
+
+type ItemProps = {
+  icon: NebulaIconName;
+  label: string;
+};
+
+export function Item({ icon, label }: ItemProps) {
+  return (
+    <div className="inline-flex items-center gap-2">
+      <NebulaIcon name={icon} size={16} />
+      <span>{label}</span>
+    </div>
+  );
+}
+```
+
+### Color y accesibilidad
+
+```tsx
+import { NebulaIcon } from 'nave-ui-icons/icons';
+
+<NebulaIcon name="Search" size={16} aria-hidden="true" />
+<NebulaIcon name="Bell" size={20} color="#652BDF" aria-hidden="true" />
+<NebulaIcon name="AlertCircle" size={20} title="Hay alertas pendientes" />
+```
+
+## Reglas de uso para el equipo
+
+1. Si el componente necesita un icono oficial del sistema, importar desde `nave-ui-icons/icons`.
+2. No importar SVGs sueltos dentro de una app si ese icono puede vivir en esta libreria.
+3. Usar `size` para escala.
+4. Usar `color` o `className` para integrarlo al estilo del componente.
+5. Para iconos decorativos, usar `aria-hidden="true"`.
+6. Para iconos con significado, usar `title` o acompanarlos con texto visible.
+7. Si falta un icono, primero agregarlo a `ui-icons` y despues consumirlo.
+
+## Que tener en cuenta al llevarla a otro proyecto
+
+- El proyecto consumidor necesita `react`.
+- El proyecto consumidor tambien debe resolver las dependencias del paquete.
+- Si vas a publicar la libreria, conviene mantener el nombre del paquete y sus subpaths estables.
+- El import para Nebula debe seguir siendo `nave-ui-icons/icons` para no romper adopcion futura.
+- Si el otro proyecto no usa el resto del monorepo, esta libreria igual puede funcionar de forma aislada porque sale compilada en `dist`.
+
+## Build y chequeos
+
+Dentro de `packages/ui-icons`:
+
+```bash
+npm run typecheck
+npm run build
+```
+
+Salida esperada:
+
+- `dist/index.*`
+- `dist/dynamic.*`
+- `dist/icons.*`
+- `dist/catalog.*`
+
+## Resumen rapido
+
+- `nave-ui-icons` = iconos estaticos
+- `nave-ui-icons/icons` = iconos Nebula del Design System
+- `NebulaIcon` = API recomendada para producto
+- si falta un icono, se agrega en esta libreria antes de usarlo en otra app