# Widget Validator Rules

> For AI: what `widgets-validate` checks and what it takes to pass. The validator is the `@modyo/widget-validator` package, at the version this MCP pins.

---

## How a widget passes

`widgets-validate` returns a `ValidationReport`:

| Field | Meaning |
|-------|---------|
| `passing` | `true` when there are **no errors**. This is the pass criterion. |
| `errors` / `warnings` | Failed checks, each with `severity`, `category`, `rule`, `message` and, when available, `file`, `line` and `suggestion` |
| `profile` | Rule set applied: `domain-1.4`, `type-based`, or `null` when `widget.manifest.json` was rejected |
| `score`, `passed`, `totalChecks` | Passed checks over total checks. Informative only |
| `version` | Version of the validator that produced the report |
| `widgetPath`, `timestamp` | Validated path (`<in-memory>` with `projectFiles`) and time of the run |

- **Warnings do not affect `passing`.** A widget with warnings (for example *Hooks Have Tests*) still passes.
- **The score is not a pass criterion.** The `stack-alignment` check that `widgets-validate` adds can set `passing: false` while the score stays at 100 (see [What `widgets-validate` adds](#what-widgets-validate-adds)).

Fix every error, run `widgets-validate` again, and stop when `passing` is `true`.

---

## Rule profiles

The validator picks a profile from `widget.manifest.json` at the widget root:

| `widget.manifest.json` | Profile |
|------------------------|---------|
| Not present | `type-based`: widgets organized by type (`src/components`, `src/services`, …) |
| `"template"` is `@dynamic-framework/dynamic-react-vite-base-template@1.x` with x ≥ 4 (prereleases included) | `domain-1.4`: widgets organized by domain (`src/app`, `src/features`, `src/shared`) |
| Anything else | None: the validation **fails closed** |

A widget created from the canonical template ships `widget.manifest.json`, so it is validated with `domain-1.4`.

### Fail closed

When the manifest exists but no profile applies, no rule runs. The report has `profile: null` and a single error in category `Widget Manifest`, rule `Profile Selection`:

| Manifest | Message |
|----------|---------|
| Not valid JSON | `widget.manifest.json is not valid JSON: <parser message>` |
| JSON that is not an object | `widget.manifest.json must contain a JSON object` |
| No `template` string | `widget.manifest.json has no "template" string (expected @dynamic-framework/dynamic-react-vite-base-template@<version>)` |
| Another package | `Unsupported template "<template>": expected @dynamic-framework/dynamic-react-vite-base-template@<version>` |
| The base template before 1.4, or another major | `Unsupported template version "<version>": this validator reads widget.manifest.json only for @dynamic-framework/dynamic-react-vite-base-template 1.4 or later within major 1` |
| Exists but cannot be read (for example, a directory) | `widget.manifest.json exists but cannot be read` |

The suggestion is to set `"template"` to the base template the widget was created from, or to remove `widget.manifest.json` if the widget uses the type-based structure.

### Missing manifest

A widget with `src/app/main.tsx` and a `src/features/` folder but **no** `widget.manifest.json` is validated as `type-based`, and every type-based folder comes back missing. The first error names the cause: category `Widget Manifest`, rule `Missing Manifest`:

- with `projectPath`: `… without widget.manifest.json, so the type-based rules were applied: add widget.manifest.json at the widget root`
- with `projectFiles`: `… so the type-based rules were applied: include widget.manifest.json in the files passed to validateWidget()`

Add the manifest (or include it in `projectFiles`) and validate again.

---

## `domain-1.4` rules

Category and rule are the names the report uses. Paths are relative to the widget root.

### Widget Manifest

| Rule | Severity | To pass |
|------|----------|---------|
| Template Version | warning | `template` is a 1.4 version. A later 1.x is validated with the same rules and gets this warning |
| Manifest Name | error | `name` equals `name` in `package.json` |
| Manifest Version | error | `version` equals `version` in `package.json` |
| Dynamic UI Pin | error | `@dynamic-framework/ui-react` is pinned to an exact version in `dependencies` (no `^` or `~`) |
| Dynamic UI Version | error | `dynamicUi` equals that pin |
| Theme Reference | error | `theme` is `null` or `package@version` |
| Design References | error | If `design` is present: a list of `{ "name", "url" }` with a non-empty name and an `https` URL |
| package.json Coherence | error | Only reported when `package.json` is missing or not valid JSON |

### Folder Structure

| Rule | Severity | To pass |
|------|----------|---------|
| Required Folders | error | `src/app`, `src/config`, `src/shared`, `src/locales`, `src/styles` and `tests` exist. `src/features` and `src/pages` are optional |

### Required Files

| Rule | Severity | To pass |
|------|----------|---------|
| Core Files | error | These files exist: `package.json`, `vite.config.ts`, `index.html`, `tsconfig.json`, `eslint.config.js`, `widget.manifest.json`, `src/app/main.tsx`, `src/app/App.tsx`, `src/app/providers/QueryProvider.tsx`, `src/config/i18nConfig.ts`, `src/config/widgetConfig.ts`, `src/shared/http/client.ts`, `src/shared/lib/errorHandler.ts`, `src/shared/lib/liquidParser.ts`, `src/locales/en.json`, `src/locales/es.json` |

### Legacy Files

| Rule | Severity | To pass |
|------|----------|---------|
| No Legacy Stack | error | None of these exist: `.config/getPlugins.js`, `webpack.config.js`, `babel.config.js`, `.babelrc`, `jest.config.js`, `jest.setup.js`, `src/store/store.ts`, `src/store/slice.ts`, `src/store/hooks.ts`, `src/store/selectors.ts`, `public/index.html`, `src/index.tsx`, `.eslintrc`, `.eslintrc.js`, `.eslintrc.json` |

### Naming Conventions

| Rule | Severity | To pass |
|------|----------|---------|
| Component Naming | error | Every `.tsx` directly inside `src/features/<name>/ui`, `src/shared/ui` and `src/pages` is `PascalCase.tsx` |
| Hook Naming | warning | Every `.ts` directly inside `src/features/<name>/hooks` and `src/shared/hooks` (except `index.ts` and files starting with `_`) is `useSomething.ts` |

### Dependencies

| Rule | Severity | To pass |
|------|----------|---------|
| Core Dependencies | error | `dependencies` declares `react`, `react-dom`, `@tanstack/react-query`, `@dynamic-framework/ui-react`, `framer-motion`, `axios`, `i18next` and `react-i18next` |
| PeerDep Version Compatibility | error | When declared, the major version is at least: `framer-motion` 12, `react-i18next` 16, `i18next` 25, `react` 18, `react-dom` 18 |
| Dev Dependencies | warning | `devDependencies` declares `typescript`, `vite`, `@vitejs/plugin-react`, `vitest` and `@testing-library/react` |
| No Legacy Dependencies | error | None of `@reduxjs/toolkit`, `react-redux`, `redux`, `webpack`, `webpack-cli`, `babel-loader`, `jest` is declared |
| package.json | error | Only reported when `package.json` is missing or not valid JSON |

### TypeScript

`tsconfig.app.json` is read when it exists; otherwise `tsconfig.json`.

| Rule | Severity | To pass |
|------|----------|---------|
| Strict Mode | error | `compilerOptions.strict` is `true` |
| JSX Transform | error | `compilerOptions.jsx` is `"react-jsx"` |
| Target Version | warning | `compilerOptions.target` is `es2020`, `es2021`, `es2022`, `es2023` or `esnext` |
| tsconfig.json | error | Only reported when `tsconfig.json` is missing or cannot be read |

### Vite Config

| Rule | Severity | To pass |
|------|----------|---------|
| React Plugin | error | `vite.config.ts` references `@vitejs/plugin-react` |
| Vitest Config | warning | `vite.config.ts` has a `test:` section, or `vitest.config.ts` exists |
| vite.config.ts | error | Only reported when `vite.config.ts` is missing |

### TanStack Query

| Rule | Severity | To pass |
|------|----------|---------|
| QueryClient | error | `src/app/providers/QueryProvider.tsx` uses `QueryClient` |
| QueryClientProvider | error | The same file uses `QueryClientProvider` |
| QueryProvider | error | Only reported when that file is missing |

### i18n

| Rule | Severity | To pass |
|------|----------|---------|
| Translation Content | error | `src/locales/en.json` and `src/locales/es.json` are JSON objects with at least one key |
| Translation Files | error | Only reported when a locale file is missing or not valid JSON |

### Testing

| Rule | Severity | To pass |
|------|----------|---------|
| Test Setup | warning | `tests/setup.ts` or `tests/setupTests.ts` exists |
| Test Files | warning | At least one `*.test.ts(x)` or `*.spec.ts(x)` file exists in the project |
| Test Infrastructure | error | Only reported when `tests/` is missing |
| Minimum Test Files | error | At least one test file exists under `tests/` |
| Hooks Have Tests | warning | Every `use*.ts` in `src/features/<name>/hooks` and `src/shared/hooks` has a test at the mirrored path: `src/<path>/useX.ts` → `tests/<path>/useX.test.ts(x)` (or `.spec`) |
| Test Folder Structure | warning | No test file lives under `src/` |

### Error Handling

| Rule | Severity | To pass |
|------|----------|---------|
| Error Handler Export | warning | `src/shared/lib/errorHandler.ts` has an export |
| Error Handler | error | Only reported when that file is missing |
| ErrorBoundary Component Exists | error | `src/shared/ui/ErrorBoundary.tsx` (or `ErrorBoundary/index.tsx`, or `ErrorBoundary/ErrorBoundary.tsx`) exists and uses `getDerivedStateFromError`, `componentDidCatch`, `DErrorBoundary` or `react-error-boundary` |
| ErrorBoundary Used in App | error | `src/app/App.tsx` imports `ErrorBoundary` and renders `<ErrorBoundary>` |

### Required Variables

| Rule | Severity | To pass |
|------|----------|---------|
| Variable Name Matches Tag | error | Each `requireVariable('<name>', …)` call in `src/config/widgetConfig.ts` passes `liquidParser.parse('{{<name>}}')` with the same name, and the name has no braces. Without calls, the check passes |

### Feature API

Checked for each folder `src/features/<name>/api/`. Without any, *API Module* passes.

| Rule | Severity | To pass |
|------|----------|---------|
| API Module | error | `api/` has at least one `.ts` module that is not `*.mock.ts`, `*.dto.ts`, `.d.ts` or `index.ts` |
| Async Functions | warning | That module exports `async` functions |
| API Mocks | warning | `api/` has at least one `*.mock.ts` |

### Portal System

| Rule | Severity | To pass |
|------|----------|---------|
| DContextProvider | warning | `src/app/main.tsx` uses `DContextProvider` |
| Portal Registration | error | `src/app/main.tsx` contains `availablePortals` |

Known limitations:

- *Portal Registration* only looks for the text `availablePortals` in `src/app/main.tsx`. It does not check which portals are registered or whether their names match the ones the widget opens.
- *Portal Registration* only runs when a `.tsx` file under `src/features` uses `<DModal` or `<DOffcanvas`. A modal elsewhere (for example in `src/pages`) is not checked.

A portal opened with a name that is not registered fails at runtime: see `modyo://docs/widgets/reference-troubleshooting`.

### UI Patterns

| Rule | Severity | To pass |
|------|----------|---------|
| No container-fluid | warning | No `.tsx` under `src` uses `className="…container-fluid…"` |

### Style Boundaries

| Rule | Severity | To pass |
|------|----------|---------|
| No Dynamic CSS Import | error | No `.ts`, `.tsx`, `.css` or `.scss` under `src` imports `dynamic-ui.css`, `dynamic-ui.min.css` or `@dynamic-framework/ui-react/src/style…`. The `abstracts/+import` partial is allowed |
| Dynamic CSS Link | error | `index.html` has an active `<link rel="stylesheet">` to Dynamic's CSS with an absolute `https://` URL |
| Dynamic CSS Version | error | The version in that URL (`…/assets/<version>/ui-react/…`) equals the `@dynamic-framework/ui-react` pin |

### Project Structure

| Rule | Severity | To pass |
|------|----------|---------|
| No extra markdown files | warning | The only `.md` file at the widget root is `README.md` |

### Data States

Checked on every `.tsx` under `src` (test files excluded).

| Rule | Severity | To pass |
|------|----------|---------|
| Loading State Handled | error | A component that destructures `data`, `isLoading` or `isPending` from a hook also handles loading: an `isLoading`/`isPending` condition, `DataStateWrapper` or `LoadingState` |
| Error State Handled | error | A component that destructures `data` from a hook also handles errors: an `isError` condition, `DataStateWrapper` or `ErrorState` |
| Empty State Handled | warning | A component that calls `data?.map`, `forEach` or `filter` also handles an empty list: a `length === 0` check, `DataStateWrapper` or `EmptyState` |

### Accessibility

| Rule | Severity | To pass |
|------|----------|---------|
| Inputs Have Labels | warning | Every `<DInput` has `label`, `aria-label` or `labelIcon` |
| Buttons Have Text | warning | Every `<DButton` with an icon has `text`, `aria-label` or children |
| Images Have Alt | warning | Every `<img` has `alt` |

### Build Output

Only checked when a `dist/` folder exists. The validator does not build: run `npm run build` first if you want this check.

| Rule | Severity | To pass |
|------|----------|---------|
| Dist Contents | warning | `dist/` contains only `main.js`, `main.css` and `index.html` |

---

## `type-based` profile

Applied to widgets without `widget.manifest.json`, organized by type (`src/components`, `src/services`, `src/store`, …). It keeps the rules that existed before the domain profile. A widget created from the canonical template never uses it.

Details: the package README, https://www.npmjs.com/package/@modyo/widget-validator.

---

## What `widgets-validate` adds

`widgets-validate` runs the validator and then one check of its own.

### `stack-alignment`

- Reads `@dynamic-framework/ui-react` from `dependencies` in the widget's `package.json` and compares its major.minor with the Dynamic UI version this MCP pins. The patch may differ.
- On a mismatch it adds an error: category `Stack Alignment`, rule `stack-alignment`, file `package.json`, and sets `passing: false`.
- It does not change `score`, `passed` or `totalChecks`: a widget can report a score of 100 and `passing: false`.
- It is skipped when `package.json` cannot be read, when it does not declare `@dynamic-framework/ui-react`, or when the declared range has no explicit numeric major.minor (`file:`, `git+ssh://`, `*`, `latest`, `2`, `2.x`).
- The message names the declared version, the pinned one, and the two ways forward: re-create the project with the `widgets-init-project` Prompt, or pass `allowLegacyStack: true`.

### `allowLegacyStack`

Optional, `false` by default. With `true`, `stack-alignment` does not run. Every validator rule still runs.

### `projectPath` and `projectFiles`

Pass exactly one:

| Input | What is validated |
|-------|-------------------|
| `projectPath` | The absolute path to the widget on the MCP server's filesystem |
| `projectFiles` | An array of `{ path, content }`, written to a temporary folder and validated there. Empty folders cannot be represented: see `modyo://docs/widgets/_meta-validator-quirks` |

---

## See also

- `modyo://docs/widgets/_meta-validator-quirks` — `projectFiles`, fail closed, missing manifest
- `modyo://docs/widgets/_meta-production-ready` — checklist before delivering
- `modyo://docs/widgets/reference-troubleshooting` — symptoms and fixes
