# Widget Generation Workflow

> For AI: the steps to build a widget with this MCP, from an empty folder to a widget ready to deploy. Project structure: `modyo://docs/widgets/reference-architecture`. Features: `modyo://docs/widgets/patterns-features`.

---

## 1. Scaffold

The operator invokes the `widgets-init-project` Prompt, whose only action is to run the `widgets-scaffold` Tool. The Tool clones the canonical template at the release tag this MCP pins and initializes the project. Never create the project or its configuration files by hand. Details: `modyo://docs/widgets/INDEX` (Base Template).

## 2. Post-clone steps

`widgets-scaffold` already renames the package, manifest, mount name and CSS class prefix (`renamedFiles` in its response). The operator copies `.modyo.example` to `.modyo` and fills in the account, token and site; the agent does not touch that file.

## 3. Functional description

Wait for the operator's functional description of the widget. Do not write widget code before receiving it.

## 4. Pattern discovery

Before writing UI, read `modyo://widgets/catalog/patterns` and look for an official pattern that matches the request. If one matches, read it from `modyo://widgets/catalog/patterns/{patternId}` and use it as the basis; if none does, say so and use components from `modyo://widgets/catalog/components`. Details: `modyo://docs/widgets/INDEX` (Pattern Discovery).

## 5. Features

Build one feature per domain by copying the reference feature `src/features/entities`, and compose the features from `src/pages/`:

1. `api/` and `model/`: endpoints, DTO, mocks, domain types, mapper (`modyo://docs/widgets/patterns-api-clients`);
2. `hooks/`: query keys and TanStack Query hooks (`modyo://docs/widgets/patterns-tanstack-query`);
3. `ui/`: components with loading, empty and error states (`modyo://docs/widgets/patterns-data-states`);
4. texts in `src/locales/es.json` and `src/locales/en.json`, used through `t('...')` (`modyo://docs/widgets/patterns-i18n`);
5. a test per layer under `tests/features/<name>/` (`modyo://docs/widgets/patterns-testing`).

Split the work by business capability, not by technical layer: each step should leave a widget that builds and shows something.

## 6. Required variables

Declare every site variable the widget needs with `requireVariable` in `src/config/widgetConfig.ts`, and give it a local value in `src/config/liquid.json`. Details: `modyo://docs/widgets/patterns-liquid-environment`.

## 7. Tests and build

In the widget project:

```bash
npm run lint
npm test
npm run build
```

`npm test` includes the boundary tests in `tests/boundaries/`. `npm run build` leaves `main.js`, `main.css` and `index.html` in `dist/`.

## 8. Validate

Run `widgets-validate` with the widget path (`projectPath`) or its files (`projectFiles`). The widget passes when the report has `passing: true`, that is, no errors; warnings do not block. Fix each error and validate again. Rules: `modyo://docs/widgets/reference-validator-rules`.

## 9. Deploy (outside the MCP)

Deployment is not an MCP operation: it runs through CI from the widget's own repository, or through an explicit `modyo-cli push` by the developer. Details: `modyo://docs/widgets/_meta-publishing`.

---

## See also

- `modyo://docs/widgets/_meta-production-ready` — checklist before delivering
- `modyo://docs/widgets/reference-troubleshooting` — symptoms and fixes
