siesa-agents 2.1.94 → 2.1.96

package/claude/skills/sa-screen-layout-refactor/SKILL.md

@@ -0,0 +1,659 @@
+---
+name: sa-screen-layout-refactor
+description: Homologate existing SIESA frontend screens to approved HTML mockups by rebuilding their UI with siesa-ui-kit components — and, when no mockup exists for a screen, do it from a learned design memory built by scanning the mockup corpus. The mockup (or the memory synthesized from the corpus) dictates distribution and element inventory (N buttons, grids, checks, labels); the installed siesa-ui-kit dictates the implementation — kit molecules and compositions of them, almost never hand-rolled HTML. Behavior never changes — no new fields, validations, endpoints or logic. Use this skill whenever the user mentions refactoring or reorganizing a screen's layout, applying an HTML mockup or a `design-artifacts` mockup to an existing page, homologating a screen to the UI kit, "reorganizar pantallas", "aplicar el mockup", "refactor de layout", "refactorizar", "redistribuir la pantalla", refactoring a module "basado en las plantillas" or "con los patrones aprendidos", scanning/updating the design memory ("escanea los prototipos", "actualiza las memorias de diseño"), or wants existing screens rebuilt with siesa-ui-kit components — even if they never use the word "refactor", even without a mockup for that screen, and even when they hand over a whole folder of mockups at once.
+---
+
+# Screen → UI-Kit Homologation (SIESA Frontend)
+
+You rebuild the UI of existing screens with siesa-ui-kit components so they
+match an approved mockup. You never change what the screen does.
+
+Read the mockup as a **component inventory and a distribution plan** — it tells
+you *what* is on the screen (a grid, five checkbox columns, two buttons, a
+summary bar) and *where* it sits. It does NOT tell you *how* to build it: the
+mockup's own HTML is throwaway Tailwind from a design tool, and copying its
+markup or classes into the app is the failure mode this skill exists to
+prevent. The *how* always comes from siesa-ui-kit:
+
+- Every widget the mockup draws is realized with a kit component ("molecule"):
+  a checkbox is the kit `Checkbox`, a data grid is the kit `Table`, a tag is
+  `Badge`, a menu is `Dropdown`.
+- When no single molecule fits, **compose** molecules: a permission matrix is
+  `Table` whose column `render` returns kit `Checkbox`es — not a hand-rolled
+  grid of styled `div`s. The kit is rich enough that most screens need zero
+  burned widget HTML.
+- Plain HTML + Tailwind is allowed only for **inert structure**: flex/grid
+  wrappers, spacing, the page scaffold of UX spec §4.3. Anything a user reads,
+  clicks, focuses or toggles belongs to the kit.
+- Existing hand-rolled widgets in the current screen ("HTML quemado") are not
+  something to preserve or restyle — they are precisely what this refactor
+  replaces with kit molecules, rewiring the existing handlers and state onto
+  the kit component's props.
+
+The integrity boundary is unchanged and non-negotiable: every field, label,
+validation, hook, query, mutation, handler and type that existed before still
+exists after, with the same name and the same behaviour. Only the rendering
+vocabulary and the distribution change. A homologation that quietly adds a
+field or drops a validation is a feature change in costume, and the diff must
+be defensible line by line against that accusation.
+
+## Sources of truth
+
+The paths below are **defaults**, resolved at setup step 0a — an explicit user
+argument or a discovered location overrides them; a path that resolves to
+nothing or to several candidates is asked about, never guessed.
+
+| What | Where | Role |
+|---|---|---|
+| Mockup queue | `_bmad-output/design-artifacts/html-and-design/*.html` (one `.html` = one screen) | WHAT is on the screen and WHERE it sits |
+| Design memory | `_bmad-output/design-artifacts/design-memory/` (`manifest.yaml` + `*.md`) | Learned distribution/composition patterns — stands in for WHAT/WHERE **only when no mockup exists**, and only per `references/design-memory.md` |
+| Installed kit exports | `apps/Frontend/node_modules/siesa-ui-kit/dist/index.d.ts` | WHICH components exist — the only authority |
+| Component props | `apps/Frontend/node_modules/siesa-ui-kit/dist/components/<Name>/<Name>.types.d.ts` | The REAL props — never guess a prop name |
+| Storybook | https://siesa-ui-kit.pages.dev | Visual catalog of variants/stories — never proof a component is importable |
+| UX spec | `_bmad-output/planning-artifacts/ux-design-specification.md` | Styles, tokens, page structure, selection priority, language rules — nothing is inferred |
+| Binding style rules | `rules/*.md` in this skill's directory | Complementary rules every generated line must obey (colors as CSS variables, rem not px, no inline styles, …) |
+| Tests | `apps/Frontend/test/unit/<module-slug>/` | The behavior contract (vitest only includes `test/unit/**`, NOT files colocated in `src/`) |
+| Reports | `_bmad-output/screen-layout-refactor/` | Per-screen and final reports |
+
+Key definitions you take from the UX spec instead of inferring:
+
+- **§2.1 Component Selection Priority** (mandatory order): 1) a siesa-ui-kit
+  molecule, 2) a **composition** of kit molecules, 3) **shadcn as the
+  fallback** when neither expresses the widget — used directly, flagged in the
+  report (`⚠️ shadcn fallback: <widget>`) so the team can later decide whether
+  to promote it into the kit. Hand-rolled HTML widgets are never an option at
+  any step. A shadcn component obeys the same `rules/` as everything else:
+  design-system token classes, rem, no inline styles — restyled to the design
+  system, never left on shadcn defaults.
+- **§1 Design System Foundation**: brand palette (primary `#0e79fd`), semantic
+  colors, surfaces; neutrals are `slate.*`, never the secondary brand scale.
+- **§4.3 Page Structure**: the standard page scaffold (header with title +
+  actions, content in a bordered rounded container).
+- **§7 Language**: all user-visible text in Spanish; never invent copy.
+- **§6 Accessibility**: WCAG 2.1 AA — the homologated screen keeps or improves
+  the accessible behavior of what it replaces.
+
+Off limits — never edit these:
+
+- `apps/Frontend/src/routes/**` (TanStack file routes, thin wrappers over pages)
+- `apps/Frontend/src/app/**`, `providers/**`, `main.tsx`, `spa.tsx` (MFE shell, single-spa, auth)
+- `apps/Frontend/src/modules/*/application|domain|infrastructure/**` (hooks, schemas, services, API)
+- The app shell (sidebar, top nav) drawn inside a mockup — mockups include it
+  for context; the screen you refactor starts at the page content.
+
+You work inside `presentation/` only. If a homologation seems to require
+touching anything above — say, the mockup shows data the page's hook doesn't
+provide — that is a signal to flag, not to widen the diff.
+
+## Design memory
+
+The skill maintains a memory of the design language learned from the mockup
+corpus, so a screen **without** a mockup can still be homologated from
+precedent. Full protocol — directory layout, `manifest.yaml` schema, SHA-256
+sync algorithm, extraction layers, file templates, memory-driven mode — lives
+in `references/design-memory.md` in this skill's directory. **Read it whenever
+memory is built, refreshed, or consumed.** The load-bearing rules, which also
+appear there:
+
+- Memory captures what only the corpus teaches: shell anatomy, screen
+  archetypes, widget → kit-composition patterns, layout rhythm. It never
+  stores hex, px, mockup theme classes, or kit prop signatures — colors and
+  measures are governed by the UX spec + `rules/`, and props are always
+  re-read from the installed typings.
+- `manifest.yaml` registers every source `.html` with its SHA-256. At setup
+  the hashes are re-checked: missing manifest → full build; new/changed
+  sources → incremental update of the attributed sections; removed sources →
+  flagged, never silently forgotten.
+- Memory is the **most junior** source of truth: an explicit mockup for the
+  target screen always outranks it, and it never overrides the UX spec, the
+  typings, or the domain.
+- A memory-driven run executes directly — no plan is printed to chat and no
+  approval turn is spent. The synthesized plan (pattern ids, homologation
+  map, distribution) is embedded in the screen's report file on disk: that is
+  the audit trail replacing the mockup link.
+
+## Anti-hallucination protocol
+
+This is the discipline that keeps the refactor honest, and it is checked in
+review:
+
+1. A kit component "exists" only if the **installed** `dist/index.d.ts`
+   exports it. Storybook routinely runs ahead of the installed package — it
+   has shown `Card` and `ButtonGroup` while the installed build exported
+   neither. If Storybook has it and the typings don't, this run realizes the
+   widget via a kit composition or the shadcn fallback (flagged, with the
+   note "or bump siesa-ui-kit and re-run this mockup") — never an import that
+   won't compile and never a hand-rolled imitation.
+
+   ```bash
+   grep -oE "^export \{[^}]+\}" apps/Frontend/node_modules/siesa-ui-kit/dist/index.d.ts
+   ```
+
+2. Props come only from the component's `.types.d.ts`. Read it before writing
+   the first JSX attribute; a prop you "remember" from another design system is
+   a compile error at best and a silent no-op at worst.
+
+3. Variants come from Storybook stories (e.g. Table: "Con Bordes", "Filas
+   Alternas", "Con Render Personalizado"; Checkbox: sizes, `labelPosition`,
+   `description`) — use them to pick the variant that matches the mockup, then
+   confirm the enabling props in the typings.
+
+4. Styling comes from the UX spec (§1 tokens, §4.3 scaffold), the binding
+   `rules/` files, and what the kit component already renders. The mockup's
+   hex values and its private Tailwind theme (`surface-container-low`,
+   `on-surface-variant`, …) never enter the codebase — per `style-rules.md`
+   they are converted on entry: hex → design-system CSS variable (via its
+   Tailwind token class), px → rem (1rem = 16px, `44px → 2.75rem`), inline
+   styles → Tailwind classes.
+
+## Pre-gate: directory validation and design memory
+
+Before asking for a target, the skill validates the two key directories and
+offers to refresh the design memory.
+
+**1. Validate `_bmad-output/design-artifacts/html-and-design`**
+
+- **Does not exist** → create it, then tell the user:
+
+  > `📁 Directorio creado: _bmad-output/design-artifacts/html-and-design`
+  > `Por favor pega en ese directorio las plantillas HTML antes de continuar.`
+
+  Stop here. The directory is the input for memory generation; proceeding
+  without templates would produce an empty memory.
+
+- **Exists** → continue.
+
+**2. Validate `_bmad-output/design-artifacts/design-memory`**
+
+- **Does not exist** → create it empty and continue (no user action needed).
+- **Exists** → continue.
+
+**3. Authorization for memory generation**
+
+Use `AskUserQuestion` with the following exact text:
+
+> *"Procederé a inspeccionar las plantillas para generar/actualizar las memorias
+> de diseño, ¿Autorizas esta acción? Esto podría tardar unos minutos."*
+
+Options: **Aceptar** / **Cancelar**.
+
+- **Aceptar** → run the full sync algorithm from `references/design-memory.md`
+  ("Sync algorithm"): hash every `.html` in `html-and-design`, compare against
+  `design-memory/manifest.yaml`, build or update only what changed. Report one
+  line: `🧠 Memory: current (N sources)` or
+  `🧠 Memory: rebuilt/updated (+A new, B changed, C removed)`.
+- **Cancelar** → explain to the user why this step matters, then stop:
+
+  > Las memorias de diseño son el insumo que permite homologar pantallas sin
+  > un mockup directo y mantener los patrones de diseño sincronizados con las
+  > plantillas más recientes. Omitir esta actualización puede causar que el
+  > refactor use patrones desactualizados o incompletos. Por este motivo, la
+  > skill no puede continuar sin ejecutar o tener memorias válidas.
+  > `❌ DETENIDO: generación de memorias cancelada por el usuario.`
+
+After this step, proceed to the Gate.
+
+## Gate: explicit target, before anything else
+
+The run starts blind and stays blind until the user names the target. The
+skill NEVER infers what to refactor — not from the queue folder's contents,
+not from recently touched files, not from the conversation's vibe. Before any
+setup step executes, the invocation must contain, or the user must answer:
+
+1. **Which module/feature of the front** is being refactored (e.g. "usuarios",
+   "conceptos", "roles y permisos"). An explicit "todo el directorio de
+   mockups" / "procesa toda la cola" counts as an answer — it is the user
+   declaring full scope, which is different from the skill assuming it.
+2. Optionally, scope modifiers (content area only, a single mockup path, a
+   custom memory dir).
+
+If the target is missing, ask (AskUserQuestion when available: "¿Qué módulo o
+feature quieres refactorizar?" listing the modules detected under the resolved
+frontend's `src/modules/` and the mockups present in the queue as options)
+and **stop until answered** — no path resolution beyond what the question
+needs, no memory build, no queue listing, no edits. Unattended with no target:
+`❌ BLOCKED: no target — a module/feature name is required to run`.
+
+Everything the user declares here defines the run's scope: mockups in the
+queue that fall outside it are reported as skipped (`⏭️ out of scope`), never
+processed "while we're at it".
+
+## Setup, once per run
+
+0a. **Resolve paths — never trust the burned-in defaults blindly.** Resolution
+   order for every path in the Sources-of-truth table: 1) an explicit user
+   argument, 2) what `design-memory/manifest.yaml` recorded on a previous run
+   (`sources_dir`, `memory_dir`, `frontend_dir`), 3) auto-discovery, 4) the
+   table's default.
+
+   **Frontend dir:** by team directive every app lives under `apps/` (backend
+   and frontend side by side), so discovery is anchored there and never
+   assumes the folder's name. The frontend is **the app that depends on
+   siesa-ui-kit** — the folder name (`Frontend`, `web`, `portal`) proves
+   nothing, the dependency does:
+
+   ```bash
+   grep -l '"siesa-ui-kit"' apps/*/package.json | xargs -r -n1 dirname
+   ```
+
+   If it resolves but `node_modules/siesa-ui-kit/dist/index.d.ts` is missing
+   inside it, the kit isn't installed — tell the user to install before
+   continuing (the typings are the component authority; without them nothing
+   downstream is trustworthy). **Artifacts:**
+
+   ```bash
+   find . -maxdepth 5 -type d -path "*design-artifacts/html-and-design" -not -path "*/node_modules/*"
+   find . -maxdepth 5 -name "ux-design-specification.md" -not -path "*/node_modules/*"
+   ```
+
+   Exactly one hit → use it (and record it in the manifest so the next run
+   skips discovery). Zero or multiple hits → interactively, ask the user;
+   unattended, `❌ BLOCKED: path resolution — <what> → <candidates found>`.
+   Everything downstream (`tsc`, vitest, module mapping, off-limits globs)
+   uses the **resolved** frontend dir; the literal `apps/Frontend` in this
+   skill's examples is just the reference layout.
+0. Read every `.md` in this skill's `rules/` directory. Each file there is a
+   binding rule set for all code this run generates or modifies — currently
+   `style-rules.md` (colors only via design-system CSS variables, all measures
+   in rem at 1rem = 16px, everything scales from the root font-size, no inline
+   styles, px/hex from specs are converted on entry, never copied). New rule
+   files dropped there later bind exactly the same way, without editing this
+   skill.
+0b. **Design memory** — already synced in the pre-gate step; skip. If the
+   user provided a custom memory path via argument, record it in
+   `manifest.yaml` now so the next run picks it up.
+1. List the queue: every `.html` in the resolved mockup dir, sorted by name —
+   that is the FIFO processing order — then **filter it to the target declared
+   at the gate**: only mockups matching the named module/feature stay in the
+   run (full-scope declarations keep everything). Out-of-scope mockups are
+   listed as `⏭️ out of scope`. A single mockup passed as an argument is a
+   one-item queue, wherever it sits on disk. Arguments may also scope the work
+   (e.g. "content area only, skip the app shell") — honor them.
+2. Confirm the kit typings are readable (`dist/index.d.ts` above). Do not wait
+   on Storybook; grep the typings.
+3. Capture the type-check baseline **before** editing anything and let it
+   finish — a killed run undercounts and you will later read your own errors
+   as pre-existing:
+
+   ```bash
+   cd apps/Frontend && npx tsc -p tsconfig.json 2>&1 | grep -c "error TS"
+   ```
+
+   Whatever the count is (0 on a green branch, dozens on a stale one), *that*
+   is the number Step 5 compares against.
+4. Branching: the git repo is the **monorepo root** (`apps/Frontend` is not its
+   own repo). Never work on `main` or `develop` — from those, create
+   `refactor/screen-layout-<slug>` at the moment of the first real edit. If the
+   session is already on a feature branch, stay on it and record that in the
+   report; yanking a user's in-flight branch around is worse than sharing it.
+5. Report the queue to the user (screen count and names), then start screen #1.
+
+## Per screen: six steps, in order
+
+### Step 1 — Validate inputs
+
+Resolve the mockup to a real screen file. In order:
+
+1. An explicit target comment in the mockup wins:
+   `<!-- target: src/modules/concepts/presentation/pages/ConceptsPage.tsx -->`
+2. Otherwise map by convention: mockup slug → module folder
+   `apps/Frontend/src/modules/<module-slug>/presentation/pages/` → the
+   `*Page.tsx` in it. Sibling `*.layout.tsx` / `*.fields.tsx` files are part of
+   the screen but not the entry point.
+3. A filename that matches no module is not automatically blocked — read the
+   mockup's content: titles and field ids usually name the module outright
+   (`roles_view_edit.html` names roles/permissions → the administracion
+   permission editor). This inference resolves a **file** inside the scope the
+   user already declared at the gate; it never decides *what* gets
+   refactored — a content match pointing outside the declared target is
+   `⏭️ out of scope`, not a new work item.
+
+If the module doesn't exist or the mapping is ambiguous (several `*Page.tsx`
+and no target comment), the screen is `❌ BLOCKED: <screen> — <what is
+missing>`. Log it, move on. Never guess a target; a refactor applied to the
+wrong file is worse than a skipped one.
+
+**If the mockup is missing but the target module is clear** (the user asked
+"refactoriza el módulo de usuarios" and no `usuarios*.html` exists), do not
+block automatically — enter **memory-driven mode** per
+`references/design-memory.md`: check memory coverage against the current
+screen's widget census, synthesize the homologation map and distribution from
+the memory patterns (citing pattern ids), record that plan in the screen's
+report, and proceed straight to Step 4 — no approval turn. Only if the memory doesn't exist, or has no precedent for
+the screen's archetype, is the screen `❌ BLOCKED: <screen> — no mockup and no
+memory precedent`. Steps 2–6 then run identically, with the synthesized plan
+standing in for the mockup.
+
+### Step 2 — Build the homologation map
+
+Inventory every widget the mockup draws — buttons, checkboxes, data grids,
+tabs, badges, dropdown menus, inputs, labels with descriptions, pagination,
+dividers, avatars — and map **each one** to its kit realization before touching
+code. The map has three possible values per element:
+
+1. **A kit molecule** — the direct case. Common mappings against the currently
+   installed kit (re-verify each against `index.d.ts`; the kit grows):
+
+   | Mockup shows | Kit realization |
+   |---|---|
+   | Checkbox (with label / description) | `Checkbox` (`label`, `description`, `labelPosition`, `indeterminate`) |
+   | Data grid / table of rows | `Table` (`TableColumn.render`, `sortable`, `align`, `width`, pagination props) |
+   | Master catalog with CRUD affordances | `MasterCrud` (the mandated orchestrator for master modules, UX spec §2.2) |
+   | Button, icon button | `Button` |
+   | Tag / status chip | `Badge` |
+   | Toggle | `Switch` |
+   | Radio group | `Radio` |
+   | Text/number/email input | `Input`, `Textarea`, `Quantity` |
+   | Dropdown / kebab menu | `Dropdown` (+ `DropdownItemHeading`, `DropdownItemCollapsible`) |
+   | Fixed-list select / async master lookup | `Select` / `LookupField` (R-LF-001: backend data is always `lookup`) |
+   | Tabs | `Tabs` |
+   | Key–value detail block | `DescriptionList` |
+   | Inline message / banner | `Alert`, `Info` |
+   | Ephemeral feedback | `Toast` |
+   | Count badge | `Notification` |
+   | Section separator | `Divider` |
+   | Pager | `Pagination` |
+   | User avatar | `Avatar` |
+
+2. **A composition** — when no single molecule fits, compose them and say so in
+   the map. The canonical example: a module × action permission matrix is
+   `Table` with one column per action whose `render` returns a `Checkbox`
+   wired to the existing toggle callback — header, borders, row hover and
+   responsive behavior come free and consistent. Before composing, check
+   `design-memory/component-patterns.md` for a learned pattern that already
+   names this composition (cite its pattern id in the map), and search the
+   repo for a sibling module that already solved it — follow precedent instead
+   of inventing a second dialect:
+
+   ```bash
+   grep -rln "<pattern>" apps/Frontend/src/modules/*/presentation apps/Frontend/src/shared
+   ```
+
+3. **Shadcn fallback** — neither a molecule nor a reasonable composition of
+   kit molecules expresses the widget. Use the shadcn component that does,
+   record it in the map as `<widget> → shadcn <Component> (⚠️ fallback)`, and
+   carry the flag into the screen report so the team can evaluate promoting it
+   into siesa-ui-kit later. The shadcn piece is restyled to the design system
+   per `rules/` (token classes, rem, no inline styles) and its props/behavior
+   are wired to the screen's existing handlers exactly as a kit molecule would
+   be. A screen no longer blocks for a missing kit component; it blocks only
+   if not even shadcn covers the widget — then
+   `❌ BLOCKED: <screen> — <widget> has no kit or shadcn realization`. What you
+   never do is hand-roll the widget out of `div`s — a local reimplementation
+   looks fine in the PR and then diverges from the design system forever.
+
+Decorative appshell chrome in the mockup (sidebar, top nav, breadcrumbs that
+belong to the shell) is out of scope — do not inventory it.
+
+Close the step with the verdict: `✅ HOMOLOGATION MAP READY` (list it) or the
+blocked line.
+
+### Step 3 — Analyze the gap
+
+With the map in hand, audit the **current** screen and write down:
+
+- **Current implementation census** — for each widget on the screen today: is
+  it already a kit molecule, or burned HTML (a styled `div` grid, a native
+  `<input type="checkbox">`, a hand-rolled table)? The burned ones are the
+  refactor targets; the kit ones may only need re-distribution or variant
+  changes.
+- **Target distribution** — where the mockup puts things (columns, order,
+  grouping, alignment, which elements sit in the header vs the body).
+- **Changes needed** — element by element: replace X with kit Y, move Z into W.
+- **Stays identical** — every field name, validation, hook call, query,
+  mutation, handler, prop and type; every aria-label and accessible behavior.
+
+Two asymmetries, both flagged, never silently resolved:
+
+- A mockup element with **no counterpart in the current screen** (an extra
+  column, a summary bar over data the page doesn't have, a subtitle showing
+  data no hook provides) is new functionality, not layout: `⚠️ WARNING` it in
+  the report and leave it out.
+- A current element with **no place in the mockup** (a bulk-toggle row, an
+  extra action column, an alert region) stays rendered somewhere sensible and
+  gets flagged. Deleting functionality to satisfy a drawing is a functional
+  change disguised as layout. The mockup is not automatically right — one once
+  drew a status switch that would have opened a second, wrong write path.
+
+### Step 4 — Refactor
+
+Decide which kind of screen you are holding; the tactic differs:
+
+**(a) Hand-written JSX** (pages that compose their own components). Execute the
+homologation map: replace each burned widget with its kit molecule or
+composition, rewiring the **existing** handlers, state, refs and accessible
+names onto the kit component's real props. The page's hooks, services and
+callbacks are untouched — only the rendering layer changes vocabulary. Keep
+whole subtrees where they already use the kit; retyped markup is where dropped
+props and renamed fields come from. Structure the page per UX spec §4.3.
+
+**(b) Kit-driven form** — one `<MasterCrud>` plus a declarative `fields[]`
+array. There is no widget HTML to replace: the kit renders the form. Do NOT
+rewrite fields — take over only the layout via `renderForm`:
+
+```tsx
+renderForm={(formProps) => {
+  const { renderField } = formProps as RenderContentArgs
+  return <MyScreenFormLayout renderField={renderField as RenderField} t={t} />
+}}
+```
+
+The hard-won mechanics, worth understanding rather than copying:
+
+- `renderForm` is not a slot for a form: the kit forwards it into its internal
+  `MasterCrudForm` as `renderContent`. Return **only the field-area content**;
+  the kit keeps its own `<form>`, save ref, header and Cancelar/Guardar footer.
+  Mounting another `<MasterCrudForm>` inside is the trap — nested forms, save
+  reads one state while fields write another: everything renders, nothing
+  saves, and no kit-mocked test notices.
+- `renderField(accessorKey)` with **no second argument** uses the kit's own
+  renderer, so every `validate`, `disabled` predicate, lookup config and
+  calculated field survives untouched. Your layout module decides only *where*
+  each `accessorKey` is painted, and `fields[]` stays complete so submit
+  validation keeps iterating every field, visible or not.
+- Two kit-side type frictions, fixed at the boundary with a comment, never by
+  loosening your types:
+  `type RenderContentArgs = Parameters<NonNullable<MasterCrudFormProps<T>['renderContent']>>[0]`
+  (the declared parameter omits `renderField`), and
+  `renderField as RenderField` where `RenderField = (accessorKey: string) => ReactNode`
+  (`inputRenderer` is typed required though omitting it is what triggers the
+  kit renderer).
+- Put the layout in a sibling `<screen>.layout.tsx` that imports no services
+  and declares no fields. If that file ever needs a validation or an API call,
+  the change stopped being layout — back to Step 3.
+
+Whichever kind: keep field `name`s/`accessorKey`s, react-hook-form
+registrations and resolvers, zod schemas, TanStack Query/Router bindings,
+`useEffect` dependencies, event handlers, i18n keys and TypeScript types
+intact. New user-visible strings only where the new structure needs an
+accessible name (a tablist label, a collapse button), in Spanish, per UX spec
+§7 — never invented copy for a mockup's decorative headings.
+
+Every line you write obeys the `rules/` files: colors only through
+design-system variables (their Tailwind token classes — `bg-primary`,
+`border-border` — never `bg-[#hex]`), measures in rem via Tailwind's scale
+(arbitrary values in rem when the scale falls short, never `w-[240px]`), no
+`style` attribute (runtime-computed values are the one commented exception),
+and any absolute value a spec or mockup hands you is converted before it
+enters the code. Burned HTML you are homologating loses its inline styles and
+hardcoded values in the same pass — translating them to kit props and Tailwind
+token classes is part of the replacement, not a follow-up.
+
+#### Delegating the implementation
+
+Steps 1–3 are this skill's job; a large Step 4 does not have to be. When the
+refactor spans several files, hand it to the `sa-dev-story` workflow with a
+brief that cannot drift: the target file, the homologation map, the
+distribution from Step 3, the mechanics above, and the Never list. Delegating
+the typing does not delegate the verdict — you still own Steps 5 and 6. Keep it
+inline when the change is one file and a handful of edits.
+
+### Step 5 — Self-verify
+
+```bash
+cd apps/Frontend && npx tsc -p tsconfig.json 2>&1 | grep "error TS" > "$TEMP/after.txt"
+wc -l < "$TEMP/after.txt"                                # compare with the setup baseline
+grep -E "<module-slug>|<new files>" "$TEMP/after.txt"    # must print nothing
+cd apps/Frontend && npx vitest run --pool=threads test/unit/<module-slug>
+```
+
+The error count is not expected to be zero — it is expected to be **the
+baseline**, with zero hits in files you touched. Tests live under
+`test/unit/<module-slug>/` (the vitest config does not include `src/`);
+`--pool=threads` works around fork-pool spawn timeouts on Windows — that
+failure is environmental, not a red test.
+
+Then enforce the `rules/` files mechanically over every file you touched —
+each grep must print nothing (a hit that predates your diff and sits outside
+the lines you changed is reported, not silently fixed):
+
+```bash
+grep -nE "#[0-9a-fA-F]{3,8}\b|rgb\(|hsl\(" <touched files>      # R1: no hardcoded colors
+grep -nE "\[[0-9.]+px\]|: ?'?[0-9.]+px" <touched files>          # R2: no px in arbitrary values or style objects
+grep -nE "style=\{|style=\"" <touched files>                     # R4: no inline styles (commented runtime exception aside)
+```
+
+Reading test failures after a homologation:
+
+- A **behavioral** assertion gone red — a value that no longer saves, a label
+  gone missing, a toggle that stopped toggling, keyboard/focus behavior lost —
+  means the refactor dropped something. Fix the refactor, never the assertion.
+- A **structural** assertion pinned to the exact markup you replaced (a
+  `data-*` attribute on a hand-rolled grid, a class name, a DOM shape) may
+  legitimately need updating *because the markup it pinned no longer exists*.
+  Update it to pin the same behavior on the kit-rendered DOM, and list every
+  such change in the report — silently weakening a test is how regressions
+  ship.
+
+**On a kit-driven form the existing unit test cannot verify your work**: those
+screens mock `siesa-ui-kit` wholesale and a mocked kit never invokes
+`renderForm`. Add one RTL test against the **real** kit that: opens the form
+and asserts the new structure; types into fields on two different
+panels/sections, switches between them and asserts values survive; submits and
+asserts the intercepted request body carries values **from both**. That last
+assertion is the only proof the regrouping did not sever a field from form
+state — the first real run of this skill caught exactly that failure. Do not
+report ✅ Done on a kit-driven form without it.
+
+Then read your own diff (`git diff -- <files>`):
+
+- [ ] Distribution matches the mockup; every widget is a kit molecule or a declared composition
+- [ ] No burned widget HTML remains in the touched area (structure wrappers are fine)
+- [ ] No mockup markup or mockup theme classes copied in
+- [ ] No field added, none removed; no validation added or modified
+- [ ] No new or changed API call; hooks and services untouched
+- [ ] Kit components used with real props (from `.types.d.ts`)
+- [ ] `rules/` compliance: colors only via token classes, measures in rem, no
+      inline styles, spec px/hex converted — the three greps above print nothing
+- [ ] Accessible behavior preserved (names, focus, keyboard) — §6
+- [ ] All user-visible text in Spanish — §7
+- [ ] Route wrapper and MFE/single-spa registration untouched
+- [ ] Types at baseline, module tests green (with any structural-assertion updates listed)
+
+### Step 6 — Report
+
+Append to `_bmad-output/screen-layout-refactor/<screen>.md` and keep going:
+
+```md
+## Screen: <name>
+**File:** <path>
+**Mode:** 📐 mockup-driven (<mockup file>) / 🧠 memory-driven (patterns: <ids>)
+**Status:** ✅ Done / ❌ Blocked / ⚠️ Warning
+
+### Homologation map
+- <mockup element> → <kit component / composition>
+
+### Layout changes applied
+- ...
+
+### Preserved unchanged
+- ...
+
+### Test updates (structural only, with reason)
+- ...
+
+### Issues / warnings
+- ...
+```
+
+## Queue behaviour
+
+Process FIFO, write each screen's report before starting the next, and let a
+blocked screen block only itself. A missing kit component no longer blocks —
+it falls back to shadcn with its flag; a screen blocks only for unresolvable
+targets, memory gaps, or widgets not even shadcn covers. Keep going until the
+queue is empty.
+
+Run one full build at the end rather than per screen
+(`cd apps/Frontend && npm run build`) — per-screen `tsc` already catches type
+breakage and the Vite build is slow enough that repeating it wastes the run.
+
+## Deliverables when the queue is empty
+
+`_bmad-output/screen-layout-refactor/FINAL_REFACTOR_REPORT.md`:
+
+```md
+| Screen | Status | Kit components used | shadcn fallbacks | Blocked reason |
+|--------|--------|---------------------|------------------|----------------|
+
+Summary:
+- Total screens processed: X
+- 🧠 Memory: <current / rebuilt> (N sources in manifest) — memory-driven screens: X
+- ✅ Homologated: X
+- ⚠️ shadcn fallbacks used: X — candidates to promote into siesa-ui-kit
+- ❌ Blocked: X — list them
+- ⚠️ Warnings requiring team review: X
+- Final build: pass / fail
+```
+
+`_bmad-output/screen-layout-refactor/INSTRUCTIVE.md` — how another team reruns
+this for their module: preparing a mockup (one `.html` per screen, optional
+`<!-- target: ... -->` comment), dropping mockups into the queue folder,
+invoking the skill, reading the report, what a `⚠️ shadcn fallback` means
+(working screen today; evaluate promoting the component into siesa-ui-kit,
+publish, bump the dependency, optionally re-run only that mockup), and what to
+do with a blocked screen.
+
+## Never
+
+- Copy the mockup's HTML, classes or theme tokens into the app — the mockup is
+  a drawing, not source code
+- Hand-roll a widget the kit owns, or restyle existing burned HTML instead of
+  replacing it with the kit molecule
+- Reach for shadcn while a kit molecule or a composition of kit molecules
+  covers the widget — shadcn is strictly the third option
+- Use a shadcn fallback without flagging it in the map and the report, or
+  leave it on shadcn default styling instead of the design-system tokens
+- Import a component the **installed** typings don't export, or use a prop not
+  in its `.types.d.ts` — Storybook is a catalog, not proof
+- Infer colors, spacing or typography — the UX spec and the kit's own rendering
+  decide
+- Hardcode a color (hex/rgb/hsl, including `bg-[#…]`): colors exist only as
+  design-system CSS variables consumed through their token classes
+- Write a fixed px measure: rem always (1rem = 16px), Tailwind's scale first,
+  arbitrary rem values second
+- Use the `style` attribute: Tailwind classes only, with runtime-computed
+  values as the sole commented exception
+- Add a field, input or form element; add or change a validation
+- Add or modify an endpoint, service, schema or backend contract
+- Remove existing functionality to make a mockup fit
+- Touch routes, navigation, MFE shell or auth layers
+- Work directly on `main` or `develop`
+- Restate a field's definition in a layout module: on a kit-driven form,
+  hand-writing inputs instead of calling `renderField` is a rewrite in costume
+- Weaken what a test verifies. Updating a structural assertion whose markup you
+  replaced is legitimate (and reported); loosening a behavioral assertion to
+  get green is not
+- Start a run without an explicit user-declared target (a module/feature name,
+  or an explicit full-scope instruction) — inferring what to refactor is
+  forbidden; process anything the declared scope doesn't cover
+- Treat the mockup as automatically right — it can contradict the domain, and
+  domain wins
+- Store hex, px, mockup theme classes or kit prop signatures in a memory file —
+  memories speak design-system vocabulary only, converted on entry
+- Use the memory when an explicit mockup for the target exists — the mockup
+  outranks it
+- Hide a memory-driven run's provenance — the synthesized plan, the pattern
+  ids used, and any `⚠️ ambiguous` resolution always go in the screen's report
+- Silently drop learned patterns when a source mockup disappears — flag it and
+  let a human retire the pattern

package/claude/skills/sa-screen-layout-refactor/references/design-memory.md

@@ -0,0 +1,235 @@
+# Design Memory Protocol
+
+Full protocol for building, refreshing and consuming the design memory. Read
+this file whenever the SKILL.md sends you here: at memory sync (setup) and
+before any memory-driven refactor.
+
+## Purpose and hard boundary
+
+The memory lets the skill refactor a screen **whose mockup does not exist**,
+by generalizing the distribution and composition patterns learned from the
+approved mockup corpus. It never replaces the other sources of truth:
+
+- Colors, typography, spacing tokens → **UX spec §1 + `rules/style-rules.md`
+  (R1–R5)**. The memory NEVER stores hex values, px, or the mockup's private
+  Tailwind theme classes (`surface-container-low`, `on-surface-variant`, …).
+  If an observation involves a measure or color, record it already converted
+  exactly as the rules mandate for code: color → the design-system utility
+  class derived from its `@theme` CSS variable (`bg-primary`,
+  `text-muted-foreground`) per R1; measure → rem at `1rem = 16px`, Tailwind
+  scale first, arbitrary rem second, per R2. If a mockup color has **no**
+  existing variable, the memory records the nearest semantic variable and the
+  finding `⚠️ design-system gap: <observed color>` (R1's gap rule) — it never
+  invents or approximates a hex.
+- Which components exist and their props → **installed typings**
+  (`dist/index.d.ts`, `.types.d.ts`). The memory records that a pattern *maps
+  to* `Table` + `Checkbox`; it never records prop signatures — those are
+  re-read from typings at use time, because the kit grows.
+- Behavior → the existing screen. Memory-driven mode changes distribution and
+  rendering vocabulary only; the integrity boundary of the skill is unchanged.
+
+A memory entry is valid only if it is written in **design-system vocabulary**:
+kit component names, compositions of them, UX-spec section references, token
+classes, rem. Mockup markup pasted into a memory file is a protocol violation.
+
+## Directory layout
+
+Default root (overridable by the user; if they give another path, use it and
+record it in the manifest):
+
+```
+_bmad-output/design-artifacts/design-memory/
+├── manifest.yaml          # registry of sources → memories (sync state)
+├── design-dna.md          # global principles + shell anatomy
+├── component-patterns.md  # recurring widget → kit realizations, with attribution
+└── layout-rhythm.md       # grid/spacing/grouping conventions (token classes, rem)
+```
+
+## manifest.yaml schema
+
+```yaml
+version: 1
+skill: sa-screen-layout-refactor
+sources_dir: _bmad-output/design-artifacts/html-and-design
+memory_dir: _bmad-output/design-artifacts/design-memory
+frontend_dir: apps/Frontend   # the app under apps/ whose package.json depends on siesa-ui-kit (setup 0a)
+updated_at: "2026-08-06T14:30:00Z"
+kit_version: "1.8.3"        # from apps/Frontend/node_modules/siesa-ui-kit/package.json
+sources:
+  - path: roles_view_edit.html
+    sha256: "3f5a…"
+    analyzed_at: "2026-08-06T14:30:00Z"
+    patterns: [shell, header-actions, permission-matrix, tabs-detail]
+  - path: concepts_master.html
+    sha256: "9b21…"
+    analyzed_at: "2026-08-06T14:30:00Z"
+    patterns: [shell, master-crud-list, lookup-filters]
+```
+
+Rules:
+
+- `sha256` is of the raw file bytes: `sha256sum <file> | cut -d' ' -f1`.
+- `patterns` is the list of pattern ids this source contributed. Every pattern
+  section in a memory file carries the same ids, so a changed source can be
+  traced to the exact sections it feeds.
+- `kit_version` is recorded so a major kit bump can prompt re-verification of
+  the component mappings (the mapping names may still be valid; their props
+  are always re-read from typings anyway).
+
+## Sync algorithm (setup, every run)
+
+```bash
+SRC=_bmad-output/design-artifacts/html-and-design
+MEM=_bmad-output/design-artifacts/design-memory
+mkdir -p "$MEM"
+for f in "$SRC"/*.html; do sha256sum "$f"; done
+```
+
+Compare against `manifest.yaml`:
+
+| State | Detection | Action |
+|---|---|---|
+| No manifest | `manifest.yaml` missing | **Full build**: run the extraction protocol over every `.html`, write the three memory files + manifest |
+| New source | hash present on disk, path absent in manifest | Analyze that file only; **merge** its patterns into the memory files (add sections or extend existing ones, with attribution); append to manifest |
+| Changed source | path present, hash differs | Re-analyze that file; update every memory section attributed to it; refresh its manifest entry |
+| Removed source | path in manifest, file gone | Do NOT silently delete learned patterns. Mark the affected sections `⚠️ source removed: <file>` and flag it in the run report — a human decides whether the pattern is retired |
+| All hashes match | — | Memory is current; skip straight to the queue |
+
+Merging discipline: prefer **generalizing** an existing pattern over adding a
+near-duplicate ("header with title + 2 actions" and "header with title + 3
+actions" are one pattern with a variable action count, not two). When two
+sources contradict each other (one groups filters above the table, another in
+a side panel), record both variants with their sources and the condition that
+selects each, if inferable; otherwise mark `⚠️ ambiguous` — memory-driven mode
+must surface the ambiguity to the user instead of picking silently.
+
+Sync is cheap when nothing changed (a hash pass), so it runs unconditionally
+at setup. Report the outcome in one line: `🧠 Memory: current (12 sources)` or
+`🧠 Memory: rebuilt/updated (+2 new, 1 changed, 0 removed)`.
+
+## Extraction protocol (per source file)
+
+Read the `.html` and extract three layers. You are reverse-engineering the
+*decisions*, not the markup — every finding is recorded in design-system
+vocabulary, converted on entry exactly as `style-rules.md` mandates for code.
+
+**Layer 1 — Shell & scaffold anatomy.** How the screen is framed: does it
+follow UX spec §4.3 (header with title + actions, content in bordered rounded
+container)? Where do primary vs secondary actions sit? Where do filters,
+breadcrumb-adjacent info, summary bars live? Ignore appshell chrome (sidebar,
+top nav) — same exclusion as Step 2 of the main flow.
+
+**Layer 2 — Component patterns.** Inventory the widgets exactly as Step 2
+does, and record the *recurring realizations*: "master list screens = kit
+`Table` with kebab `Dropdown` per row + `Pagination` below, page header hosts
+the create `Button`", "permission matrix = `Table` whose action columns
+`render` kit `Checkbox`es", "detail blocks = `DescriptionList`, never label/
+value divs". Each pattern gets: an id (slug), the mockup evidence (which
+files, which region), the kit realization, and any variant conditions. A
+pattern whose realization is a shadcn fallback is recorded with
+`**Kit realization:** shadcn <Component> (⚠️ provisional — promote to kit?)`
+and re-checked against the installed typings on every sync: the moment the
+kit exports a covering molecule, the pattern is updated and the flag dropped.
+
+**Layer 3 — Rhythm & grouping.** Constant structural choices translated to
+tokens per R2/R5: column counts and breakpoints of form grids, gap scale
+between sections vs between fields (as Tailwind scale steps / rem), grouping
+logic (what gets a bordered container vs a plain block, when sections become
+`Tabs`), density (labels above vs beside inputs). If the mockup says `24px`,
+the memory says `gap-6` (1.5rem); if a value has no exact scale step, record
+the arbitrary rem (`gap-[0.8125rem]`), preserving the design's proportions —
+R5 forbids eyeballing to a nearby token that changes the visual ratio, and a
+non-1:1 conversion is noted in the entry.
+
+Reasoning ("why") is welcome when it is inferable and useful for improvising
+new screens — e.g. "destructive actions are always rightmost and ghost-style"
+— but never invent rationale; unlabeled observations are fine.
+
+## Memory file templates
+
+`design-dna.md`:
+
+```markdown
+# Design DNA — <project>
+_Manifest: see manifest.yaml. Vocabulary: siesa-ui-kit + UX spec tokens only._
+
+## Visual principles
+- <principle> (evidence: <files>)
+
+## Shell & scaffold
+- <observation, referencing UX spec §4.3 where it matches> (evidence: …)
+
+## Screen archetypes
+- **master-crud-list** — <one-line anatomy> → details in component-patterns.md
+- **detail-edit** — …
+```
+
+`component-patterns.md` (one section per pattern id):
+
+```markdown
+## pattern: permission-matrix
+**Sources:** roles_view_edit.html
+**Mockup shows:** module × action grid of checkboxes with sticky first column
+**Kit realization:** `Table` — one column per action, `TableColumn.render`
+returns `Checkbox` wired to the existing toggle handler; first column plain
+text.
+**Variants / conditions:** —
+**Notes:** re-verify `Table`/`Checkbox` props in `.types.d.ts` at use time.
+```
+
+`layout-rhythm.md`:
+
+```markdown
+## Form grids
+- 2-column `grid-cols-2 gap-x-6 gap-y-4`, collapsing to 1 below `md` (evidence: …)
+
+## Section spacing
+- Between page sections: `gap-8`; inside a bordered container: `p-6` (evidence: …)
+```
+
+## Memory-driven mode (no mockup for the target)
+
+Entered from Step 1 of the main flow when the user asks to refactor a module
+that has no `.html` in the queue, and memories exist.
+
+1. **Coverage check.** Census the current screen (Step 3's inventory, done
+   early) and match it against memory patterns. Every widget class on the
+   screen must be covered by a pattern, by the Step 2 molecule table, or by
+   the shadcn fallback (Step 2 case 3 — flagged as always).
+   - Full coverage → proceed.
+   - A screen archetype the memory has never seen (e.g. a wizard, when all
+     sources are master lists) → `❌ BLOCKED: <screen> — no memory precedent
+     for <archetype>; provide a mockup or approve pattern extrapolation`.
+     Individual unfamiliar widgets don't block (kit table or shadcn covers
+     them); an unfamiliar *whole-screen shape* does, because there is no
+     precedent to synthesize the distribution from.
+2. **Synthesize the plan.** Build the homologation map (Step 2) from
+   `component-patterns.md`, and the target distribution (Step 3) from
+   `design-dna.md` + `layout-rhythm.md`, citing pattern ids for every
+   decision. This synthesized plan plays the role the mockup normally plays.
+   Ambiguous patterns (`⚠️ ambiguous`) are resolved by majority evidence and
+   flagged in the report, never silently.
+3. **Execute directly — no approval turn.** Do not print the plan to chat or
+   wait for a go/no-go; that spends tokens and a round-trip per screen. The
+   synthesized plan is written into the screen's report file instead. An
+   `⚠️ ambiguous` pattern is resolved by the variant with the most source
+   evidence and the choice is flagged in the report — never silently.
+4. **Execute** Steps 4–6 exactly as the main flow, same integrity boundary,
+   same greps, same tests.
+5. **Report** with `Mode: 🧠 memory-driven`, the pattern ids used, and the
+   synthesized plan embedded — that is the audit trail replacing the mockup
+   link, and it is where a reviewer validates the run after the fact.
+   Recommend generating the mockup a posteriori if the team wants the corpus
+   to stay canonical.
+
+## Never (memory-specific)
+
+- Store hex, px, or mockup theme classes in a memory file — convert on entry
+  (R1: variable/utility class; R2: rem ÷ 16; R5: proportions preserved) and
+  flag `⚠️ design-system gap` when no variable covers the observed color
+- Store kit prop signatures — typings are read live, memory only names components
+- Print a memory-driven plan to chat or wait for approval — execution is
+  direct; the plan, pattern ids and ambiguity resolutions live in the report
+- Silently drop patterns when a source file disappears — flag, let a human retire
+- Let memory override the UX spec, the typings, or the domain — memory is the
+  most junior source of truth in the table

package/claude/skills/sa-screen-layout-refactor/rules/style-rules.md

@@ -0,0 +1,109 @@
+# Reglas complementarias de estilo — VINCULANTES
+
+Estas reglas aplican a **todo** el código que la skill genere o modifique, sin
+excepción y sin necesidad de que el usuario las repita. Se leen al inicio de
+cada ejecución, junto con cualquier otro archivo que exista en este directorio
+`rules/` (todo archivo aquí es igualmente vinculante; agregar una regla nueva
+es soltar un `.md` aquí).
+
+Cuando una regla de este archivo choque con lo que dibuja un mockup o con lo
+que dice una spec en valores absolutos, **la regla gana**: se convierte el
+valor, nunca se copia.
+
+---
+
+## R1 — Colores: nunca hexadecimales hardcodeados
+
+- Prohibido escribir colores en hexadecimal, `rgb()`, `hsl()` o nombres CSS
+  (`#889911`, `rgb(14 121 253)`, `red`) en JSX, CSS o valores arbitrarios de
+  Tailwind (`bg-[#0e79fd]` está prohibido igual que `style="color:#0e79fd"`).
+- Todo color se consume desde una **variable CSS del sistema de diseño**
+  (`--color-primary`, `--color-border`, `--color-muted-foreground`, …).
+- En este codebase las variables viven en el `@theme` de
+  `apps/Frontend/src/index.css` (Tailwind v4), y se consumen por su clase
+  utilitaria derivada: `bg-primary`, `text-muted-foreground`, `border-border`,
+  `bg-card`. Esa clase ES la variable — no hay paso manual de `var()`.
+- Si el color que pide el diseño no existe como variable, **no se inventa ni
+  se aproxima con un hex**: se reporta como brecha del sistema de diseño
+  (⚠️ en el reporte) y se usa la variable semántica más cercana ya definida.
+
+```tsx
+// ❌ Prohibido
+<span className="text-[#64748b] bg-[#f8fafc]">…</span>
+<div style={{ borderColor: '#e2e8f0' }}>…</div>
+
+// ✅ Correcto
+<span className="text-muted-foreground bg-muted">…</span>
+<div className="border-border">…</div>
+```
+
+## R2 — Unidades: rem, nunca px
+
+- Prohibidos los valores fijos en píxeles en clases arbitrarias, CSS y props
+  de estilo. Toda medida se expresa en **rem**, asumiendo `1rem = 16px`.
+- Conversión: `px ÷ 16 = rem`. Ejemplos: `44px → 2.75rem`, `24px → 1.5rem`,
+  `12px → 0.75rem`, `2px → 0.125rem`.
+- La escala estándar de Tailwind ya emite rem — `p-4` (1rem), `w-48` (12rem),
+  `text-sm` (0.875rem) — así que la regla en la práctica es: **usa la escala
+  de Tailwind primero**; si no alcanza, valor arbitrario en rem
+  (`w-[2.75rem]`), jamás en px (`w-[44px]`).
+- Excepción única: propiedades donde el px es semánticamente correcto e
+  independiente de la tipografía (`border` de 1px vía `border`,
+  `outline-offset` de hairlines). Ante la duda, rem.
+
+```tsx
+// ❌ Prohibido
+<div className="w-[240px] gap-[16px] text-[13px]">…</div>
+
+// ✅ Correcto
+<div className="w-60 gap-4 text-[0.8125rem]">…</div>
+```
+
+## R3 — Escalabilidad: todo cuelga del font-size raíz
+
+- El diseño completo debe escalar modificando únicamente el `font-size`
+  global del documento. Esa es la razón de R2: un layout en rem escala solo;
+  un layout en px queda congelado.
+- No fijar `font-size` en `html`/`:root` desde código de pantalla, ni usar
+  unidades que rompan la cadena (px en tipografía, alturas de línea
+  absolutas).
+- Al componer con el ui-kit esto sale gratis (el kit ya respeta el root); la
+  regla protege los wrappers estructurales y valores arbitrarios que la skill
+  escriba.
+
+## R4 — Sin estilos inline: solo clases de Tailwind
+
+- Prohibido el atributo `style` (`style="…"` / `style={{ … }}`) en el código
+  generado. Todo estilo se expresa con clases de Tailwind.
+- Si un estilo llega inline (de un mockup, de código existente que se está
+  homologando), se **traduce** a su clase Tailwind equivalente en el mismo
+  cambio.
+- Excepción única y justificada en comentario: valores imposibles de expresar
+  como clase porque son datos en runtime (p. ej. `gridTemplateColumns`
+  calculado sobre N columnas dinámicas, posiciones medidas). Debe quedar
+  comentado por qué, y el valor sigue obedeciendo R1/R2 (variables y rem).
+
+```tsx
+// ❌ Prohibido
+<div style={{ display: 'flex', gap: '16px', color: '#0e79fd' }}>…</div>
+
+// ✅ Correcto
+<div className="flex gap-4 text-primary">…</div>
+```
+
+## R5 — Consistencia con UX: convertir, no copiar
+
+- Cuando una spec de UX, un mockup o un diseño entregue valores en px o
+  colores absolutos, se convierten **automáticamente** al entrar al código:
+  px → rem (R2), hex → variable del sistema (R1), inline → Tailwind (R4).
+- La conversión respeta las **proporciones** del diseño original: un espaciado
+  del doble en el mockup sigue siendo el doble en rem; no se "redondea" a ojo
+  a un token que cambie la relación visual.
+- El resultado se declara en el reporte cuando la conversión no fue 1:1 (p.
+  ej. un px sin token exacto que se resolvió al paso más cercano de la escala).
+
+---
+
+**Entrega siempre código limpio, consistente y alineado con estas reglas.**
+Un diff que las viole no se reporta como ✅ Done: la verificación del Step 5
+de la skill incluye greps que las hacen cumplir.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "siesa-agents",
-  "version": "2.1.94",
+  "version": "2.1.96",
   "description": "Paquete para instalar y configurar agentes SIESA en tu proyecto",
   "main": "index.js",
   "bin": {