@ng-solid/mcp 22.0.0

package/data/skills/ns-solid-components/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: ns-solid-components
+description: Reference for @ng-solid/design-system's public component catalog — parent/child composition rules, service-driven components, and internal subcomponents that are not part of the public API.
+---
+
+# Catálogo de componentes de ng-solid
+
+## Tabla generada
+
+| Selector | Clase | Familia | Categoría |
+| --- | --- | --- | --- |
+| `ns-accordion` | `NsAccordionComponent` | accordion | Contenido |
+| `ns-accordion-item` | `NsAccordionItemComponent` | accordion | — |
+| `ns-alert` | `NsAlertComponent` | alert | Feedback |
+| `ns-avatar` | `NsAvatarComponent` | avatar | Contenido |
+| `ns-badge` | `NsBadgeComponent` | badge | Feedback |
+| `ns-breadcrumb-item` | `NsBreadcrumbItemComponent` | breadcrumbs | — |
+| `ns-breadcrumbs` | `NsBreadcrumbsComponent` | breadcrumbs | Navegación |
+| `ns-button` | `NsButtonComponent` | button | Acciones |
+| `ns-button-group` | `NsButtonGroupComponent` | button-group | Acciones |
+| `ns-card` | `NsCardComponent` | card | Superficies |
+| `ns-card-body` | `NsCardBodyComponent` | card | — |
+| `ns-card-footer` | `NsCardFooterComponent` | card | — |
+| `ns-card-header` | `NsCardHeaderComponent` | card | — |
+| `ns-checkbox` | `NsCheckboxComponent` | form/checkbox | Formularios |
+| `ns-chip` | `NsChipComponent` | chip | Feedback |
+| `ns-comment` | `NsCommentComponent` | comment | Formularios |
+| `ns-content-editable` | `NsContentEditableComponent` | form/directives | Formularios |
+| `ns-date-picker` | `NsDatePickerComponent` | form/date-picker | Formularios |
+| `ns-date-range-picker` | `NsDateRangePickerComponent` | form/date-picker | Formularios |
+| `ns-description` | `NsDescriptionComponent` | description | Accesibilidad |
+| `ns-divider` | `NsDividerComponent` | divider | Contenido |
+| `ns-drawer` | `NsDrawerComponent` | drawer | Overlays |
+| `ns-dropdown` | `NsDropdownComponent` | form/dropdown | Formularios |
+| `ns-dropdown-item` | `NsDropdownItemDirective` | form/dropdown | — |
+| `ns-editor` | `NsEditorComponent` | editor | Formularios |
+| `ns-editor-color-picker` | `NsEditorColorPickerComponent` | editor | — |
+| `ns-editor-link` | `NsEditorLinkComponent` | editor | — |
+| `ns-editor-list` | `NsEditorListComponent` | editor | — |
+| `ns-editor-paragraph` | `NsEditorParagraphComponent` | editor | — |
+| `ns-editor-toggle` | `NsEditorToggleCommandComponent` | editor | — |
+| `[nsField]` | `NsFieldDirective` | a11y | — |
+| `ns-image-upload` | `NsImageUploadComponent` | image-upload | Formularios |
+| `ns-input` | `NsInputComponent` | form/input | Formularios |
+| `ns-input-code` | `NsInputCodeComponent` | form/input-code | Formularios |
+| `ns-input-group` | `NsInputGroupComponent` | form/input-group | Formularios |
+| `ns-input-group-addon` | `NsInputGroupAddonComponent` | form/input-group | — |
+| `ns-input-number` | `NsInputNumberComponent` | form/input-number | Formularios |
+| `ns-input-search` | `NsInputSearchComponent` | form/input-search | Formularios |
+| `ns-link` | `NsLinkComponent` | link | Navegación |
+| `ns-meter` | `NsMeterComponent` | meter | Datos |
+| `ns-modal` | `NsModalComponent` | modal | Overlays |
+| `ns-pagination` | `NsPaginationComponent` | pagination | Navegación |
+| `ns-password` | `NsPasswordComponent` | form/password | Formularios |
+| `ns-popover` | `NsPopoverComponent` | popover | Overlays |
+| `ns-progress-bar` | `NsProgressBarComponent` | progress-bar | Feedback |
+| `ns-radio` | `NsRadioComponent` | form/radio | Formularios |
+| `ns-radio-group` | `NsRadioGroupComponent` | form/radio | Formularios |
+| `ns-schedule` | `NsScheduleComponent` | schedule | Datos |
+| `ns-schema` | `NsSchemaMarkupComponent` | schema | — |
+| `ns-skeleton` | `NsSkeletonComponent` | skeleton | Feedback |
+| `ns-slider` | `NsSliderComponent` | form/slider | Formularios |
+| `ns-surface` | `NsSurfaceComponent` | surface | Superficies |
+| `ns-switch` | `NsSwitchComponent` | form/switch | Formularios |
+| `ns-tab` | `NsTabComponent` | tabs | — |
+| `ns-tabs` | `NsTabsComponent` | tabs | Navegación |
+| `ns-tag` | `NsTagComponent` | tag-group | — |
+| `ns-tag-group` | `NsTagGroupComponent` | tag-group | Formularios |
+| `[nsTemplate]` | `TemplateDirective` | template | — |
+| `ns-textarea` | `NsTextAreaComponent` | form/text-area | Formularios |
+| `ns-toast` | `NsToastComponent` | toast | Feedback |
+| `ns-tooltip` | `NsTooltipComponent` | tooltip | — |
+| `[nsTooltip]` | `NsTooltipDirective` | tooltip | Overlays |
+
+Todos se importan desde `@ng-solid/design-system` (entry point único —
+ver la skill `ns-solid-install`) y son standalone: deben declararse en
+`imports: [...]` de quien los usa.
+
+## Reglas de composición padre → hijo
+
+Estos pares no son componentes independientes: el hijo sólo tiene sentido
+proyectado dentro del padre, y ambos deben estar en `imports`:
+
+| Padre            | Hijo(s)                                            | Notas                                                                                                                                            |
+| ---------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `ns-tabs`        | `ns-tab`                                           | Cada `ns-tab` es una pestaña; `ns-tabs` las descubre vía `contentChildren(NsTabComponent)`.                                                      |
+| `ns-card`        | `ns-card-header`, `ns-card-body`, `ns-card-footer` | Tres selectores adicionales del mismo fichero `card.component.ts`; son slots con nombre, no requieren los tres a la vez.                         |
+| `ns-accordion`   | `ns-accordion-item`                                | `ns-accordion` gestiona `expandedKeys` como `model()`; los items son sólo presentación + trigger.                                                |
+| `ns-dropdown`    | `ns-dropdown-item`                                 | `ns-dropdown-item` es una **directiva** (`NsDropdownItemDirective`), no un componente — se aplica sobre el elemento que hace de opción.          |
+| `ns-tag-group`   | `ns-tag`                                           | Agrupa chips seleccionables/removibles.                                                                                                          |
+| `ns-breadcrumbs` | `ns-breadcrumb-item`                               | Cada nivel de la ruta es un `ns-breadcrumb-item`.                                                                                                |
+| `ns-radio-group` | `ns-radio`                                         | `ns-radio-group` es el `ControlValueAccessor` (hereda de `NsValueAccessor`, ver `ns-solid-forms`); `ns-radio` por sí solo **no** implementa CVA. |
+
+`ns-input-group` es sólo un wrapper de layout — no tiene `label` ni `wrap`;
+los inputs de formulario y sus labels van en el `ns-input`/`ns-input-number`
+proyectado dentro (`ns-input-group-addon` para prefijos/sufijos).
+
+## Componentes que se usan vía servicio
+
+Estos no se instancian con una etiqueta en el template del consumidor — se
+abren/gestionan imperativamente inyectando el servicio correspondiente:
+
+- **`NsToastService`** → produce instancias de `ns-toast` (y el
+  subcomponente interno `ns-toast-region` que las hostea).
+- **`NsModalService`** → abre `ns-modal`, con contenido proyectado o un
+  `contentComponent` tipado.
+- **`NsDrawerService`** → abre `ns-drawer`.
+- **`NsScheduleService`** → coordina el estado del calendario detrás de
+  `ns-schedule` y sus celdas/eventos internos.
+
+`NsThemeService` (ver `ns-solid-theming`) y `NsOverlayService` (posicionamiento,
+focus trap, scroll lock, `inert` — usado internamente por
+popover/tooltip/drawer/modal) también son servicios públicos, pero no
+"envuelven" un componente de la misma forma.
+
+## Subcomponentes internos — no exportados
+
+Existen en el código pero **no** están en el barrel público
+(`visibility: 'internal'` en el snapshot). Un agente no debe importarlos ni
+sugerirlos; si un usuario pregunta por ellos, la respuesta correcta es
+señalar el componente público que los engloba:
+
+- `ns-schedule-cell`, `ns-schedule-day`, `ns-schedule-event`,
+  `ns-schedule-week`, `ns-schedule-workweek` → usar `ns-schedule`.
+- `ns-date-picker-calendar` → usar `ns-date-picker` / `ns-date-range-picker`.
+- `ns-toast-region` → se instancia sólo a través de `NsToastService`, nunca
+  directamente.
+
+## Variantes visuales — lenguaje HeroUI
+
+Los nombres de variante son consistentes entre componentes:
+
+- `solid` — relleno de acción sólido.
+- `soft` — versión plana (`flat` en HeroUI).
+- `outline` — bordeada (`bordered` en HeroUI).
+- `ghost` — ligera (`light` en HeroUI).
+
+Cada familia posee sus propios tokens `--ns-component-<familia>-*` — no
+tomes prestados los tokens de otro componente aunque el valor visual
+coincida.

package/data/skills/ns-solid-forms/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: ns-solid-forms
+description: Build forms with @ng-solid/design-system's ControlValueAccessor controls — formControlName/[(value)] bindings, the 14 inputs inherited from NsValueAccessor, and [nsField] wiring.
+---
+
+# Formularios con ng-solid
+
+## Controles CVA y sus inputs heredados
+
+| Selector | Clase | Inputs propios (además de los 14 heredados) |
+| --- | --- | --- |
+| `ns-checkbox` | `NsCheckboxComponent` | — |
+| `ns-content-editable` | `NsContentEditableComponent` | `maxLength` |
+| `ns-date-picker` | `NsDatePickerComponent` | `firstDayOfWeek`, `maxDate`, `minDate`, `unavailableDates` |
+| `ns-date-range-picker` | `NsDateRangePickerComponent` | `firstDayOfWeek`, `maxDate`, `minDate`, `unavailableDates` |
+| `ns-dropdown` | `NsDropdownComponent` | `collection`, `emptyText`, `loading`, `placement`, `searchable`, `searchPlaceholder`, `selectionMode` |
+| `ns-input` | `NsInputComponent` | — |
+| `ns-input-code` | `NsInputCodeComponent` | `length` |
+| `ns-input-number` | `NsInputNumberComponent` | `currency`, `format`, `max`, `min`, `step` |
+| `ns-input-search` | `NsInputSearchComponent` | — |
+| `ns-password` | `NsPasswordComponent` | `forgotLink`, `showAndHide` |
+| `ns-radio-group` | `NsRadioGroupComponent` | — |
+| `ns-slider` | `NsSliderComponent` | `max`, `min`, `range`, `step` |
+| `ns-switch` | `NsSwitchComponent` | — |
+| `ns-textarea` | `NsTextAreaComponent` | `rows` |
+
+Todos heredan de `NsValueAccessor`: 14 `input()` (`type`, `placeholder`, `label`, `description`, `errorMessage`, `required`, `invalid`, `readonly`, `name`, `ariaLabel`, `ariaDescribedBy`, `size`, `color`, `variant`) más `disabled` y `value` como `model()`.
+
+Todos implementan `ControlValueAccessor` extendiendo la clase base abstracta
+`NsValueAccessor<T>`
+(`packages/design-system/src/lib/form/models/value-accessor.ts`). Muchos
+componentes (`NsInputComponent`, `NsSwitchComponent`, `NsCheckboxComponent`…)
+tienen cuerpo de clase vacío — **toda** su API pública viene por herencia. Si
+consultas la API de un control y ves 0 inputs propios, no significa que el
+componente no acepte nada: revisa `inheritedFrom: 'NsValueAccessor'`.
+
+`NsValueAccessor` expone, en todos los controles por igual:
+
+- `type`, `placeholder`, `label`, `description`, `errorMessage`, `required`,
+  `invalid`, `readonly`, `name`, `ariaLabel`, `ariaDescribedBy` — `input()`.
+- `size: 'sm' | 'md' | 'lg'` (default `'md'`), `color: 'neutral' | 'primary'
+| 'success' | 'warning' | 'danger'` (default `'neutral'`), `variant:
+'solid' | 'soft' | 'outline' | 'ghost'` (default `'outline'`) — `input()`.
+- `disabled` — **`model()`**, no `input()`. Por eso `formControl.disable()` /
+  `.enable()` funciona de forma transparente: `setDisabledState` (parte del
+  contrato `ControlValueAccessor`) llama a `this.disabled.set(isDisabled)`
+  por debajo.
+- `value` — también `model()`, escrito por Angular Forms vía `writeValue` y
+  leído/emitido por el propio control con `setValue()`.
+
+## Bindings — los tres equivalentes
+
+```html
+<!-- Reactive Forms -->
+<ns-input formControlName="email" label="Correo" />
+
+<!-- Template-driven -->
+<ns-input [(ngModel)]="email" label="Correo" />
+
+<!-- Binding directo al model, sin FormsModule -->
+<ns-input [(value)]="email" label="Correo" />
+```
+
+Los tres funcionan porque el control implementa `ControlValueAccessor` (los
+dos primeros) y expone `value` como `model()` (el tercero). Para
+`disabled` como two-way binding equivalente: `[(disabled)]="isDisabled"`.
+
+## `[nsField]` — vincular label, descripción y error
+
+`NsFieldDirective` (selector `[nsField]`,
+`packages/design-system/src/lib/a11y/field-context.ts`) provee un
+`NsFieldContext` al subárbol. El control lo consume vía `inject(NsFieldContext,
+{ optional: true, skipSelf: true })` para resolver su `id` real
+(`controlId()`), y componentes como `NsDescriptionComponent` (hint) se
+registran contra el mismo contexto para el `aria-describedby`:
+
+```html
+<div nsField="email">
+  <ns-input formControlName="email" label="Correo" />
+  <ns-description id="email-hint"
+    >Usaremos este correo para notificarte.</ns-description
+  >
+</div>
+```
+
+Sin `[nsField]`, cada control genera su propio id vía `NsAriaIdService`; con
+él, el id explícito (`nsField="email"`) gana y el `aria-describedby` se
+compone automáticamente con las descripciones registradas en el contexto.
+
+## `errorMessage` + `invalid`
+
+El mensaje de error sólo se renderiza cuando **ambos** están presentes:
+`invalid()` es `true` y `errorMessage()` no es vacío/undefined (ver
+`input.component.html`: `@if (invalid() && errorMessage())`). Calcula
+`invalid` desde el estado del `FormControl`, no lo dejes fijo:
+
+```html
+<ns-input
+  [invalid]="control.invalid && control.touched"
+  [errorMessage]="
+    control.hasError('required') ? 'Este campo es obligatorio' : undefined
+  "
+/>
+```
+
+## Ejemplo completo con `FormBuilder`
+
+```ts
+import { Component, inject } from '@angular/core';
+import { FormBuilder, ReactiveFormsModule, Validators } from '@angular/forms';
+import {
+  NsButtonComponent,
+  NsFieldDirective,
+  NsInputComponent,
+  NsPasswordComponent,
+  NsSwitchComponent
+} from '@ng-solid/design-system';
+
+@Component({
+  selector: 'app-signup-form',
+  standalone: true,
+  imports: [
+    ReactiveFormsModule,
+    NsFieldDirective,
+    NsInputComponent,
+    NsPasswordComponent,
+    NsSwitchComponent,
+    NsButtonComponent
+  ],
+  template: `
+    <form [formGroup]="form" (ngSubmit)="submit()">
+      <div nsField="signup-email">
+        <ns-input
+          formControlName="email"
+          label="Correo"
+          type="email"
+          [invalid]="form.controls.email.invalid && form.controls.email.touched"
+          [errorMessage]="'Ingresa un correo válido'"
+        />
+      </div>
+
+      <div nsField="signup-password">
+        <ns-password
+          formControlName="password"
+          label="Contraseña"
+          [invalid]="
+            form.controls.password.invalid && form.controls.password.touched
+          "
+          [errorMessage]="'Mínimo 8 caracteres'"
+        />
+      </div>
+
+      <ns-switch formControlName="acceptTerms" label="Acepto los términos" />
+
+      <ns-button variant="primary" type="submit" [disabled]="form.invalid">
+        Crear cuenta
+      </ns-button>
+    </form>
+  `
+})
+export class SignupFormComponent {
+  private readonly fb = inject(FormBuilder);
+
+  readonly form = this.fb.group({
+    email: this.fb.control('', [Validators.required, Validators.email]),
+    password: this.fb.control('', [
+      Validators.required,
+      Validators.minLength(8)
+    ]),
+    acceptTerms: this.fb.control(false, [Validators.requiredTrue])
+  });
+
+  submit(): void {
+    if (this.form.valid) {
+      // this.form.getRawValue()
+    }
+  }
+}
+```
+
+Nota: `NsPasswordComponent` añade `forgotLink` y `showAndHide` propios sobre
+la base heredada; `NsSwitchComponent` no añade inputs propios (todo viene de
+`NsValueAccessor`).

package/data/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
+
+**1790 iconos** Lucide registrados en el catálogo (`NS_ICON_COUNT`), licencia ISC.
+
+- 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/data/skills/ns-solid-install/SKILL.md

@@ -0,0 +1,120 @@
+---
+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:
+
+- `@ng-solid/design-system@22.2.1` (peer `@angular/*@^21.0.0`)
+- `@ng-solid/icons@22.1.0`
+
+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/data/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.