@ng-solid/mcp 22.0.0

package/skills/ns-solid-icons/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: ns-solid-icons
+description: Render Lucide icons with @ng-solid/icons' <ns-icon> component — registering symbols with provideIcons/provideIconsPatch and resolving camelCase symbol names.
+---
+
+# Iconos con @ng-solid/icons
+
+## El componente `<ns-icon>`
+
+```html
+<ns-icon name="alarm-clock" [size]="20" />
+```
+
+`NsIconsComponent` (selector `ns-icon`) acepta:
+
+- `name: string` — el nombre **kebab-case** del icono Lucide (`alarm-clock`,
+  no `alarmClock`).
+- `size: number` (default `24`) — acepta el atributo plano (`numberAttribute`),
+  así que `<ns-icon name="x" size="16">` también funciona.
+- `color: string` (default `'currentColor'`).
+- `strokeWidth: number` (default `2`).
+- `viewBox: string` (default `'0 0 24 24'`).
+
+Internamente resuelve el SVG contra un `Map` poblado por
+`provideIcons`/`provideIconsPatch`; si el nombre no fue registrado, emite un
+`console.warn` y no renderiza el path.
+
+## Registrar iconos — dos providers, dos momentos distintos
+
+**`provideIcons(icons)`** — en el bootstrap de la app (`appConfig.providers`
+o `bootstrapApplication`). Usar para los iconos que se necesitan siempre:
+
+```ts
+import { provideIcons, alarmClock, x } from '@ng-solid/icons';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    // ...
+    provideIcons([alarmClock, x])
+  ]
+};
+```
+
+**`provideIconsPatch(icons)`** — a nivel de `Route.providers`, para iconos
+que sólo hace falta cargar cuando se navega a esa ruta (lazy):
+
+```ts
+const routes: Routes = [
+  {
+    path: 'products',
+    providers: [provideIconsPatch([alarmClock])],
+    loadComponent: () =>
+      import('./products.component').then((m) => m.ProductsComponent)
+  }
+];
+```
+
+`provideIconsPatch` registra además `NsIconsPatchService`, que
+`NsIconsComponent` detecta e invoca (`doPatch()`) antes de intentar resolver
+el icono, para que el registro parcial se aplique aunque el componente ya
+esté instanciado.
+
+## Los símbolos se importan en camelCase
+
+El catálogo generado (`packages/icons/src/lib/generated/index.ts`) exporta
+un símbolo por icono con el nombre kebab-case convertido a camelCase:
+
+| Icono (`name` en `<ns-icon>`)     | Símbolo importado de `@ng-solid/icons` |
+| --------------------------------- | -------------------------------------- |
+| `alarm-clock`                     | `alarmClock`                           |
+| `a-arrow-down`                    | `aArrowDown`                           |
+| `align-horizontal-justify-center` | `alignHorizontalJustifyCenter`         |
+| `circle-check`                    | `circleCheck`                          |
+
+Cada símbolo es un objeto `{ name, icon }` (ver `NsIconDefinition`) — nunca
+pases un string al provider, pasa el símbolo importado.
+
+## Catálogo
+
+<!-- ns:icon-count -->
+
+- Fuente: Lucide (`LUCIDE_SOURCE_URL` en `packages/icons/src/lib/generated/metadata.ts`).
+- Licencia: **ISC** (`LUCIDE_SOURCE_LICENSE`).
+- Usa la tool `search_icons` del MCP para encontrar el `name`/símbolo correcto
+  por palabra clave en vez de adivinar el nombre exacto de Lucide.
+
+## Errores comunes
+
+- Registrar el símbolo pero usar un `name` distinto en el template (deben
+  coincidir exactamente, kebab-case).
+- Olvidar `provideIcons`/`provideIconsPatch` por completo — el icono no
+  truena, simplemente no renderiza y deja un warning en consola.
+- Confundir `provideIcons` (bootstrap, global) con `provideIconsPatch`
+  (`Route.providers`, por ruta) — usar el segundo en el bootstrap no falla,
+  pero pierde el propósito de carga diferida.

package/skills/ns-solid-install/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: ns-solid-install
+description: Install and bootstrap @ng-solid/design-system (Arvisfy) plus @ng-solid/icons in an Angular 21 standalone application, including the Tailwind bridge and theme provider.
+---
+
+# Instalación de @ng-solid/design-system
+
+## Paquetes y peer dependencies
+
+```bash
+pnpm add @ng-solid/design-system @ng-solid/icons
+```
+
+`@ng-solid/design-system` declara estos peer dependencies (ver
+`packages/design-system/package.json`):
+
+- `@angular/core`, `@angular/common`, `@angular/forms`,
+  `@angular/platform-browser`, `@angular/router` en `^21.0.0`.
+- `@ng-solid/icons` en `^22.0.5`.
+- `tailwindcss` en `^4.0.0`, marcado **opcional** (`peerDependenciesMeta`) —
+  sólo hace falta si la app consume el puente de utilidades semánticas.
+
+Versiones publicadas actualmente:
+
+<!-- ns:versions -->
+
+Si tu app usa Tailwind, añade también el plugin de PostCSS:
+
+```bash
+pnpm add -D tailwindcss @tailwindcss/postcss
+```
+
+## Entrypoint único — nada de subpaths
+
+`@ng-solid/design-system` tiene **un solo entry point público**
+(`ng-package.json` → `entryFile: src/index.ts`, sin `secondaryEntrypoints`).
+Todo se importa desde la raíz del paquete:
+
+```ts
+import { NsButtonComponent, NsInputComponent } from '@ng-solid/design-system';
+```
+
+Nunca inventes rutas como `@ng-solid/design-system/button` — no existen. La
+única excepción es el asset CSS publicado explícitamente como
+`@ng-solid/design-system/themes/tailwind.css` (ver más abajo), que no es un
+entry point de JS/TS.
+
+## Puente de Tailwind
+
+Si la app importa el puente semántico, hazlo una sola vez en el stylesheet
+global, después de las capas de Tailwind:
+
+```css
+@import '@ng-solid/design-system/themes/tailwind.css';
+```
+
+Ese fichero define el bridge `@theme inline` que mapea los tokens de
+Tailwind a `--ns-semantic-*`, además de registrar localmente la fuente
+variable Inter (sin peticiones de red en runtime).
+
+## Registrar el tema en `appConfig`
+
+```ts
+import { Arvisfy, provideNsTheme } from '@ng-solid/design-system';
+import { ApplicationConfig } from '@angular/core';
+
+export const appConfig: ApplicationConfig = {
+  providers: [provideNsTheme({ preset: Arvisfy, colorScheme: 'system' })]
+};
+```
+
+`colorScheme: 'system'` sigue `prefers-color-scheme`. Ver la skill
+`ns-solid-theming` para `defineNsPreset`, `NsThemeService.setScheme` y las
+reglas de validación del preset.
+
+## Standalone: `imports` es obligatorio
+
+Todos los componentes son **standalone**. Angular no los resuelve
+automáticamente: hay que declararlos explícitamente en el `imports` del
+componente (o del `NgModule`) que los usa. Omitir esto es el error más común
+al generar código con un agente:
+
+```ts
+import { Component } from '@angular/core';
+import { NsButtonComponent } from '@ng-solid/design-system';
+
+@Component({
+  selector: 'app-toolbar',
+  standalone: true,
+  imports: [NsButtonComponent], // obligatorio — <ns-button> no funciona sin esto
+  template: `<ns-button variant="primary">Guardar</ns-button>`
+})
+export class ToolbarComponent {}
+```
+
+Esto vale también para directivas de composición (`NsFieldDirective`,
+`NsTooltipDirective`, `NsDropdownItemDirective`, etc.) y para componentes
+usados vía `contentChildren`/proyección (`ns-card-header`, `ns-tab`,
+`ns-accordion-item`…): todos deben aparecer en `imports`.
+
+## Iconos
+
+`@ng-solid/icons` se instala aparte y se registra con `provideIcons(...)` en
+el bootstrap. Ver la skill `ns-solid-icons` para el detalle completo
+(símbolos camelCase, `provideIconsPatch` para rutas con lazy loading).
+
+## Extender el preset
+
+No copies `Arvisfy`; extiéndelo con `defineNsPreset` (ver `ns-solid-theming`
+para las reglas de validación completas):
+
+```ts
+import { Arvisfy, defineNsPreset } from '@ng-solid/design-system';
+
+export const ProductTheme = defineNsPreset(Arvisfy, {
+  name: 'product',
+  primitive: { color: { brand: { 500: '#0052ff' } } }
+});
+```

package/skills/ns-solid-style-contract/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: ns-solid-style-contract
+description: Follow ng-solid's enforced style architecture — ns-* BEM class naming, zero Tailwind utilities in markup, and the @reference-only SCSS contract checked by pnpm quality:styles.
+---
+
+# Contrato de estilos de ng-solid
+
+Este contrato lo enforcea en CI
+`tools/scripts/check-design-system-styles.mjs` (`pnpm quality:styles`) sobre
+`packages/design-system/src/lib` y `apps/demo/src`. Un PR que lo viole falla
+el build, tanto en la librería como en aplicaciones que sigan la misma
+convención.
+
+## 1. Clases de template: sólo `ns-*` BEM
+
+Toda clase en `class="…"`, `[class.x]` o claves de objeto `[ngClass]` debe
+matchear:
+
+```
+ns-block__element--modifier
+```
+
+Regex real usada por el gate:
+
+```
+/^ns-[a-z0-9]+(?:-[a-z0-9]+)*(?:(?:__[a-z0-9]+(?:-[a-z0-9]+)*)?(?:--[a-z0-9]+(?:-[a-z0-9]+)*)?)?$/
+```
+
+Válido: `ns-button`, `ns-button__icon`, `ns-button--danger`,
+`ns-card__header--sticky`. Inválido: `btn-primary`, `NsButton`,
+`ns_button`, `flex`.
+
+## 2. Cero utilidades Tailwind en markup
+
+Ninguna clase de template puede empezar con un prefijo de utilidad Tailwind
+(`flex`, `grid`, `gap-`, `p-`/`m-` + variantes, `text-`, `bg-`, `border`,
+`rounded`, `shadow`, `absolute`/`relative`/`fixed`/`sticky`, `inset`/`top-`/
+`bottom-`/`start-`/`end-`, `z-`, `w-`/`h-`, `min-`/`max-`, `overflow`,
+`opacity`, `font-`, `items-`/`justify-`/`content-`). Tailwind se compone
+**sólo** desde SCSS con `@apply`, nunca directamente en el HTML.
+
+## 3. Nada de `styles:` inline
+
+Un componente no puede declarar estilos inline en el decorador
+(`styles: [...]`). Usa `styleUrl` (o `styleUrls`) apuntando a un `.scss`
+hermano.
+
+## 4. SCSS de componente: `@reference`, sin `@use`/`@import`, sin valores crudos
+
+Cada `.scss` de componente (fuera de `lib/theme/`) debe:
+
+- Incluir literalmente `@reference` (al bridge de Tailwind:
+  `@reference '../theme/tailwind.css';` o la ruta relativa que corresponda).
+- **No** usar `@use` ni `@import` — extender Tailwind sólo vía `@reference`.
+- **No** contener valores crudos: hex (`#fff`), `rgb()`/`rgba()`, literales
+  `px`/`rem`/`em`/`ms`/`s`, o `var(--x, fallback)` con valor por defecto.
+  Toda decisión visual se lee de un token `--ns-component-*` ya resuelto por
+  el preset (ver la skill `ns-solid-theming`) — sin fallback embebido, porque
+  el preset garantiza que la variable siempre está definida.
+
+Ejemplo correcto:
+
+```scss
+@reference '../theme/tailwind.css';
+
+.ns-button {
+  @apply inline-flex items-center;
+  background: var(--ns-component-button-background);
+  color: var(--ns-component-button-foreground);
+}
+```
+
+## 5. Prohibido reintroducir Bootstrap / `@popperjs`
+
+El gate falla si `package.json` o `pnpm-lock.yaml` vuelven a traer
+`bootstrap` o `@popperjs/*` — el design-system fue migrado fuera de esas
+dependencias deliberadamente.
+
+## Validar un snippet antes de proponerlo
+
+Usa la tool del MCP `validate_style_contract` (o `validate_component_usage`
+para un uso completo de componente) contra cualquier markup/SCSS que generes
+antes de entregarlo — es la misma lógica que corre `pnpm quality:styles`,
+expuesta como función pura.

package/skills/ns-solid-theming/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: ns-solid-theming
+description: Work with the Arvisfy three-tier token architecture in @ng-solid/design-system — extending the preset, validating tokens and switching color scheme at runtime.
+---
+
+# Theming con Arvisfy
+
+## Los tres niveles de tokens
+
+`packages/design-system/src/lib/theme/presets/arvisfy.preset.ts` define el
+preset en tres tiers, cada uno sólo puede referenciar al tier anterior:
+
+1. **`primitive`** — únicos valores crudos permitidos (hex, `rem`, pesos de
+   fuente, escalas numéricas). Ejemplo real: `primitive.color.klein.500 =
+'#3665F3'`.
+2. **`semantic`** — referencia primitivos con la sintaxis `{primitive.…}`, y
+   se divide en `common` (independiente de esquema) y
+   `colorScheme.light` / `colorScheme.dark` (un valor distinto por esquema).
+3. **`components`** — referencia semánticos con `{semantic.…}`. Es el único
+   tier que las hojas de estilo de componente pueden consumir, y sólo a
+   través de la variable CSS resultante.
+
+Conteo actual del preset Arvisfy:
+
+<!-- ns:token-count -->
+
+## Regla de oro del SCSS de componente
+
+El SCSS de un componente **sólo** puede leer variables `--ns-component-*`.
+Nunca `--ns-primitive-*` ni `--ns-semantic-*` directamente, y nunca un valor
+crudo (hex, `rgb()`, `px`/`rem`/`ms` literal) — eso lo enforcea
+`pnpm quality:styles` (ver la skill `ns-solid-style-contract`).
+
+La conversión de un path de token a variable CSS es determinista
+(`tokenPathToCssVariable` en `theme.utils.ts`): camelCase se separa en
+kebab-case y los puntos se vuelven guiones, con el tier como prefijo:
+
+```
+tier: 'component', path: 'button.background'
+  -> --ns-component-button-background
+```
+
+## Extender el preset — nunca copiarlo
+
+```ts
+import { Arvisfy, defineNsPreset } from '@ng-solid/design-system';
+
+export const ProductTheme = defineNsPreset(Arvisfy, {
+  name: 'product',
+  primitive: {
+    color: { brand: { 500: '#0052ff' } }
+  },
+  semantic: {
+    colorScheme: {
+      light: { color: { primary: '{primitive.color.brand.500}' } },
+      dark: { color: { primary: '{primitive.color.brand.500}' } }
+    }
+  },
+  components: {
+    button: { borderColor: '{semantic.color.primary}' }
+  }
+});
+```
+
+`defineNsPreset(base, overrides)` hace un merge profundo (`overrides` gana
+por clave) y llama a `validateNsPreset` sobre el resultado antes de
+devolverlo. `NsThemeService` también valida el preset activo en su
+constructor y en cada `setPreset`.
+
+## Reglas que aplica `validateNsPreset`
+
+Extraídas de `packages/design-system/src/lib/theme/utils/theme.utils.ts`:
+
+- **Nombre del preset**: debe matchear `/^[a-z][a-z0-9-]*$/i` (falla si no).
+- **Claves de token**: cada segmento del path debe matchear
+  `/^(?:[a-z][a-zA-Z0-9]*|[0-9]+)$/` — sin guiones ni mayúsculas iniciales.
+- **Valores primitivos seguros**: ningún string primitivo puede contener
+  `;`, `{` o `}`, ni estar vacío.
+- **Referencias `semantic.*`**: todo valor de `semantic.common` /
+  `semantic.colorScheme.{light,dark}` debe tener la forma exacta
+  `{primitive.<path>}` y ese `<path>` debe existir en `primitive`.
+- **Referencias `components.*`**: todo valor debe tener la forma
+  `{semantic.<path>}`, y ese `<path>` debe existir en `semantic.common`, o
+  en **ambos** `colorScheme.light` y `colorScheme.dark` a la vez — un token
+  de componente que sólo resuelve en un esquema es un preset inválido.
+
+Cualquier violación lanza una excepción síncrona (`throw new Error(...)`),
+no un warning: un preset inválido rompe el arranque de la app.
+
+## Cambiar de esquema en runtime
+
+```ts
+import { inject } from '@angular/core';
+import { NsThemeService } from '@ng-solid/design-system';
+
+const theme = inject(NsThemeService);
+theme.setScheme('dark'); // 'light' | 'dark' | 'system'
+```
+
+- `'system'` delega en `prefers-color-scheme` y reacciona a cambios en vivo
+  vía `matchMedia('(prefers-color-scheme: dark)')`.
+- Una elección explícita (`'light'` / `'dark'`) se persiste en
+  `localStorage` bajo la clave `ns-color-scheme` (configurable con
+  `provideNsTheme({ storageKey: '...' })`, o desactivable con
+  `storageKey: false`).
+- `NsThemeService` expone `preset`, `colorScheme`, `resolvedColorScheme`
+  (siempre `'light' | 'dark'`, nunca `'system'`) y `scheme` como signals de
+  sólo lectura.
+- Al aplicar el tema, el servicio escribe todas las custom properties en
+  `documentElement.style` y además `dataset.nsPreset` / `dataset.nsColorScheme`
+  y `style.colorScheme`, para que el navegador ajuste scrollbars/controles
+  nativos.
+
+## Configurar el provider
+
+```ts
+provideNsTheme({
+  preset: Arvisfy,
+  colorScheme: 'system', // default
+  storageKey: 'ns-color-scheme', // default; false para desactivar persistencia
+  toast: { placement: 'top-end' } // default de NsToastService
+});
+```