siesa-agents 2.1.93 → 2.1.95

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

@@ -0,0 +1,616 @@
+---
+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.
+
+## 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. **Sync the design memory** (`references/design-memory.md`, "Sync
+   algorithm"): hash every `.html` in the mockup dir and compare against
+   `design-memory/manifest.yaml`. No manifest → full build of the memory
+   files; new/changed/removed sources → incremental update / flag; all hashes
+   match → skip. Report one line: `🧠 Memory: current (N sources)` or
+   `🧠 Memory: rebuilt/updated (+A new, B changed, C removed)`. If the user
+   provided a custom memory path, use it and record it in the manifest.
+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