# Praxis Form Layout Canvas

> Use when Codex must work on @praxisui/dynamic-form or praxis-dynamic-form package layout materialization, schema-driven layout policy, generated layout presets, layout editor, visual blocks, FormColumn.items, canvas editors, section/row/column/field placement, compact presentation, grouped command forms, or visual layout validation.

- Skill: `codexrodrigues/praxis-form-layout-canvas` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx get-skill add codexrodrigues/praxis-form-layout-canvas`
- Raw SKILL.md: https://api.skillmd.com/api/skills/codexrodrigues/praxis-form-layout-canvas/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: codexrodrigues (https://skillmd.com/u/codexrodrigues)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/codexrodrigues/praxis-form-layout-canvas

---


# Praxis Form Layout Canvas

This `praxis-form-*` skill family is the canonical Codex skill surface for `@praxisui/dynamic-form` and `projects/praxis-dynamic-form`; do not create parallel `praxis-dynamic-form-*` guidance unless this family cannot express a proven contract gap.

Use this skill for Dynamic Form layout, visual blocks, canvas, and schema-driven layout materialization. Layout is a governed projection of field metadata and authoring config; it must not become a second source of business semantics.

## Source Audit

Inspect the affected source:

- `projects/praxis-dynamic-form/AGENTS.md`
- `projects/praxis-dynamic-form/src/lib/dynamic-form-editor-document.model.ts`
- `projects/praxis-dynamic-form/src/lib/praxis-dynamic-form-widget-config-editor.ts`
- `projects/praxis-dynamic-form/src/lib/filter-form/praxis-filter-form-widget-config-editor.ts`
- `projects/praxis-dynamic-form/src/lib/ai/praxis-dynamic-form-authoring-manifest.ts`
- `projects/praxis-dynamic-form/src/lib/ai/dynamic-form-rule-authoring-context.ts`
- `projects/praxis-dynamic-form/src/lib/layout-editor/**`
- `projects/praxis-dynamic-form/src/lib/canvas/**`
- `projects/praxis-dynamic-form/src/lib/services/dynamic-form-layout.service.ts`
- `projects/praxis-dynamic-form/src/lib/services/form-layout.service.ts`
- `projects/praxis-dynamic-form/src/lib/services/form-config.service.ts`
- `projects/praxis-dynamic-form/src/lib/utils/normalize-form-config.ts`
- `projects/praxis-dynamic-form/src/lib/utils/section-header.utils.ts`
- `projects/praxis-dynamic-form/src/lib/utils/visual-block-rule-content-overrides.util.ts`
- `projects/praxis-dynamic-form/docs/schema-driven-layout-materialization-rfc.md`
- `projects/praxis-dynamic-form/docs/layout-items-visual-blocks.md`
- `projects/praxis-dynamic-form/docs/dynamic-form-authoring-document-semantics.md`
- `projects/praxis-dynamic-form/docs/dynamic-form-rules-authoring-plan.md`
- `projects/praxis-dynamic-form/docs/dynamic-form-visual-builder-parity-audit.md`
- `projects/praxis-dynamic-form/docs/hot-metadata-updates.md`
- related JSON API docs such as `layout-editor/praxis-layout-editor.json-api.md` and `config-editor/praxis-dynamic-form-config-editor.json-api.md`

Inspect `@praxisui/core` form layout models when changing `FormConfig`, `FormLayout`, `FormColumn.items`, visual block rules, or `DynamicFormLayoutPolicy`.

Concrete `@praxisui/core` files to inspect for layout ownership and schema materialization:

- `projects/praxis-core/src/lib/models/form/form-config.model.ts`
- `projects/praxis-core/src/lib/models/form/form-config.model.spec.ts`
- `projects/praxis-core/src/lib/models/form/form-layout-items.model.ts`
- `projects/praxis-core/src/lib/helpers/ensure-ids.helper.ts`
- `projects/praxis-core/src/lib/helpers/ensure-ids.helper.spec.ts`
- `projects/praxis-core/src/lib/helpers/form-layout-materializer.ts`
- `projects/praxis-core/src/lib/helpers/form-layout-materializer.spec.ts`
- `projects/praxis-core/src/lib/services/surface-open-materializer.service.ts`
- `projects/praxis-core/src/lib/services/surface-open-materializer.service.spec.ts`
- `projects/praxis-core/src/lib/widgets/dynamic-widget-loader.directive.ts`
- `projects/praxis-core/src/lib/widgets/dynamic-widget-loader.directive.spec.ts`

## Canonical Layout Rules

- `FormColumn.items[]` is the canonical order for fields and visual blocks inside a column.
- `fields[]` is only a compatibility/migration projection.
- API fields remain in `fieldMetadata[]` and appear in layout as `items[]` with `kind: "field"`.
- Visual blocks are `items[]` with `kind: "richContent"` and a valid `RichContentDocument`.
- Visual blocks do not create `FormControl`, do not enter `fieldMetadata[]`, and do not enter submit payloads.
- Presets are authoring shortcuts only; persisted runtime semantics are still rich content documents.
- `DynamicFormAuthoringDocument` is the complete authoring snapshot. Do not persist runtime/discovery-only values such as host `schemaUrl`, `submitUrl`, or `submitMethod` inside authoring bindings.
- Numeric layout authoring must match Core's integer grid domains and the runtime utility classes. Test fractional, non-finite, out-of-range, and inherited values through the column editor and JSON apply path. Runtime recovery must not silently rewrite the authored document; invalid drafts must block Apply/Save and identify the field and breakpoint. Revalidate JSON at Apply time, not only after a debounced edit.
- Row occupancy is authoring guidance, not a requirement to fill 12 units. Include responsive offsets, exclude breakpoint-hidden columns and columns with only statically hidden fields, and preserve intentional whitespace. Empty draft columns and visual blocks still participate. Suggestions must remain explicit, use the same occupancy calculation and never rewrite metadata or layout on inspection. Do not present this static guidance as a simulation of record-dependent rules.
- Visibility commands must preserve geometry, ordering and style. Before changing smaller breakpoints, resolve inheritance so that an action scoped to them does not unintentionally hide larger breakpoints. Test presets against a customized column, not only default full-width fixtures.
- Layout editor, canvas editor, config editor, JSON editor, and AI authoring must round-trip the same `FormConfig.sections[].rows[].columns[].items[]` semantics.
- For individual field movement, expose and validate the existing selected-field **Move field** dialog as a keyboard-accessible alternative to drag. Choose section/row/column and position through `moveLayoutItemById`; preserve item IDs, metadata, mixed-item order and empty containers. The destination column owns geometry/style. Opening/cancelling must not dirty the document; reject an obsolete destination snapshot and move focus to the selected field after confirmation. Validate Apply → Save/close → Save page → reload separately, then restore the baseline when simulating on a user composition.
- Destination summaries must derive from canonical `items[]` and metadata labels, preserve stable IDs as option values, account for visual blocks/empty destinations, and bound long lists without treating static summaries as visibility/permission simulation.
- For visual-block destinations, reuse the internal `visual-block-label.ts` extraction shared with the row editor. Bound plain-text previews and distinguish identical/empty blocks by original column item position (including the moving field); never use preview text or position as persisted identity, evaluate bindings/HTML, or infer a preset from CSS classes. Validate duplicate text with distinct IDs and multiline options in a narrow dialog.
- Visual-block preview shortcuts must handle Enter/Space only when the preview itself is the event target. Nested native buttons own their activation: do not open the content editor or prevent Space on their behalf. Validate menu open/remove by keyboard, preview edit/select shortcuts, unchanged document on inspection, and add/remove returning to a clean draft. After insertion/reorder/column movement, continue focus on the selected block; after removal, select/focus its preserved column. Guard deferred focus against a newer selection. Test through a parent that clones emitted config: object-reference equality alone must not suppress valid focus restoration.
- Scope `DynamicFormLayoutService` to each `LayoutEditorComponent` draft: root `changes$` is observed by live forms, so using that root instance for draft operations bypasses Apply and leaks cancelled changes into runtime. Validate both same-page discard/reopen and explicit Apply; a reload or an unchanged HTTP payload alone cannot prove draft isolation.
- Section quick rename must reuse `FormSection.title` and the existing update event, preserve IDs/structure/appearance, reject blank names, and support Enter/Escape with focus return. Empty-section guidance should invoke the existing add-row command with translated copy and host tokens. When validating section removal, check that eligible unplaced API fields return to the palette without deleting metadata, then discard/reopen on the same page; visual blocks belong to the removed structure and are not recoverable API fields. Tests of output-driven operations must reproduce the owning editor's output-to-input binding.
- Section spacing is `FormSection.gapBottom`, the space after the whole section, not a column gap or editor density. Inspect `LayoutEditorComponent.canApplyAll/applyGapToAll` and `docs/section-spacing-authoring-2026-09-08.md`: fill only absent/null values, preserve explicit zero and other authored gaps, reject negative/non-finite proposals, and emit nothing for a proposal change or an ineligible document. Do not generate or consult `gapCustomized` as a second source of eligibility. Validate through the owning output-to-input flow, including same-page discard/reopen; a draft-only check does not prove persisted runtime spacing.
- Rule targets may include visual blocks, sections, rows, columns, actions, and fields, but visual-block rules remain visual-only and must not mutate domain payload semantics.
- Normalize IDs and legacy layout shape through the shared core helpers. `ensureIds(...)` must preserve rich content items, normalize legacy `fields[]` into canonical `items[]`, and keep `fields[]` synchronized as a field-only projection.
- Use `getFormColumnFieldNames(...)`/layout item helpers instead of reading `column.fields` directly when code must understand current field order.
- Surface materialization can project read data into Dynamic Form `initialValue` and a transient schema `layoutPolicy`; that is runtime materialization, not authored local `FormConfig.sections`.
- Dynamic widget loading must pass `layoutPolicy` and related runtime inputs through to Dynamic Form instead of flattening them into host-specific config.
- "Add API field" means place an existing `fieldMetadata[].name` into canonical `items[]`
  (`kind: "field"`) and preserve `fieldMetadata[]`. It is not permission to create DTO/schema
  fields, clone metadata, or patch backend semantics from the canvas.
- Audit the existing column-menu Add API field path before inventing another placement contract. Explain it in palette/empty-column copy, validate Enter/arrow navigation, and focus the inserted field after rendering: the old menu trigger may be destroyed by the layout update. Tab must continue into the field controls; reject already placed/unknown candidates and verify discard/reopen returns the field to the available catalogue.
- Local fields are a separate authoring path and must carry safe local semantics such as
  `source: "local"`, `transient: true`, and `submitPolicy: "omit"` unless a submit contract
  explicitly owns them. Do not use a local field to stand in for missing backend metadata.

Do not represent visual guidance as local fields, transient fields, DTO fields, or backend metadata unless it is genuinely domain data.

## Schema-Driven Layout Policy

Treat schema-driven layout as opt-in and explicit:

- default remains authored config.
- `layoutPolicy.source = "schema"` makes schema metadata the layout source for that runtime surface.
- `compactPresentation` with `intent: "detail"` is for read-only detail summaries.
- `groupedCommand` is for create/edit command forms.
- `groupedCommand.partialRowStrategy` is the canonical policy for incomplete rows. Default
  `preserve` keeps authored/schema widths unchanged. `fill-compatible` may widen only eligible,
  known, non-compact controls to the next supported grid span (`3`, `4`, `6`, `8`, `12`) so the
  visible row fills 12 columns; it must not rewrite the underlying field width contract.
- Resolve `fill-compatible` independently for each visible row and each active responsive
  breakpoint. Hidden fields change row membership, so a desktop projection cannot be reused for
  tablet or narrow layouts. Dynamic Form owns this runtime projection and should use its named
  form-row container rather than global viewport guesses.
- Put `container-type`/`container-name` on an element with measurable inline size that actually
  contains the responsive columns, such as `.form-row.grid-12`. Never name a `display: contents`
  wrapper as the query container: its zero-size box leaves responsive span classes present in the
  DOM but permanently inactive.
- authored `FormConfig.sections` must not be silently overwritten unless policy says schema owns layout.
- non-layout config, such as actions, messages, hooks, behavior, submit behavior, and hints, can still come from authored config.
- `DynamicFormLayoutPolicy.schemaType` and `schemaOperation` must agree with the schema URL when declared. Detail/read-only surfaces use response schema; create/edit command surfaces use request schema.
- `SurfaceOpenMaterializerService` may default read projections to `compactPresentation` + `schemaType: "response"` and related command forms to `groupedCommand` + `schemaType: "request"`. Fix this materializer or discovery metadata before copying local sections into consumers.
- With `layoutPolicy.source="schema"` and `persistence="transient"`, generated sections, rows,
  columns, `items[]`, spans, and section order are runtime projections. Opening the editor or
  Settings Panel must not convert them into authored config unless an explicit detach/authorable
  flow is chosen.

Classify repeated local section configs as `ja-suportado-mal-nomeado-ou-mal-materializado` or `suportado-parcialmente` before proposing backend metadata changes. The backend may already publish `group`, `order`, `width`, labels, help text, read-only hints, and presentation metadata.

### Grouped command context

`groupedCommand.contextFields` preserves declared hidden metadata fields in the form
and submission while excluding them from interactive layout. Inspect Core's
`form-layout-materializer.ts` and tests for this split. Selection IDs and expected
versions materialized by resource-action discovery must survive; do not expose them
as editable fields or restore them with a host submit hook. Verify metadata retention,
layout omission and the actual request payload, including hidden context fields.

## Inventory Before New Contract

- `ja-suportado-so-ux`: `items[]`, layout policy, visual block, or schema metadata already supports the need, but the canvas/editor does not expose the workflow clearly.
- `ja-suportado-mal-nomeado-ou-mal-materializado`: local `sections`, `fields[]`, visual seeds, labels, or presets duplicate semantics already present in `fieldMetadata[]`, `items[]`, schema metadata, or `DynamicFormAuthoringDocument`.
- `suportado-parcialmente`: runtime layout works, but editor round-trip, canvas state, JSON editor, AI manifest, visual builder parity, docs, responsive UX, or submit-boundary tests are incomplete.
- `lacuna-real-de-contrato`: no `FormConfig`, `FormLayout`, `FormColumn.items`, `DynamicFormLayoutPolicy`, authoring document, schema metadata, or visual-block contract can represent the layout decision.

Only `lacuna-real-de-contrato` justifies a new public layout contract. Otherwise, repair the missing projection, editor affordance, validation, or documentation in the existing chain.

## AI/Canvas Rules

- AI and canvas authoring must resolve the semantic layout operation first: add API field, reorder field, add visual block, move section/row/column, apply preset, materialize schema layout, or configure compact/grouped presentation.
- Do not route layout intent primarily by text labels, section names, CSS classes, or visual position guesses. Use canonical field names, layout item IDs, `kind`, authoring manifest operations, and schema metadata as grounding.
- Canvas state may store selection, focus, draft edits, drag state, or diagnostics. It must not become the owner of field order, field semantics, visual block document shape, submit payload, or schema-derived layout policy.
- When schema owns layout, generated sections are transient. Do not persist generated schema sections back into authored config unless the product explicitly supports an authoring conversion flow.
- When authored config owns layout, schema metadata can enrich labels, help, width, group, and read-only hints, but it must not silently overwrite authored structure.
- For Ergon or other migration consumers, treat repeated hand-authored sections as transitional debt when DTO/schema metadata can own grouping/order. Document consumer work separately instead of hardcoding Ergon-specific shortcuts into Praxis.
- For Ergon-style operational screens, prefer schema-owned grouping/order/width for scalable
  detail and command surfaces. If the layout only looks correct after local sections, local labels,
  duplicated visual seeds, or fake hidden fields, route the gap to metadata/schema materialization
  or consumer follow-up instead of institutionalizing that screen as a Praxis layout pattern.

## Validation

- Layout editor: `npx ng test praxis-dynamic-form --watch=false --progress=false --include=projects/praxis-dynamic-form/src/lib/layout-editor/layout-editor.component.spec.ts --include=projects/praxis-dynamic-form/src/lib/layout-editor/field-configurator.component.spec.ts --include=projects/praxis-dynamic-form/src/lib/layout-editor/row-configurator.component.spec.ts --include=projects/praxis-dynamic-form/src/lib/layout-editor/section-configurator.component.spec.ts --include=projects/praxis-dynamic-form/src/lib/layout-editor/apply-section-preset.util.spec.ts --include=projects/praxis-dynamic-form/src/lib/layout-editor/visual-block-presets.spec.ts`
- Canvas editor: `npx ng test praxis-dynamic-form --watch=false --progress=false --include=projects/praxis-dynamic-form/src/lib/canvas/components/section-editor/section-editor.component.spec.ts --include=projects/praxis-dynamic-form/src/lib/canvas/components/row-editor/row-editor.component.spec.ts --include=projects/praxis-dynamic-form/src/lib/canvas/components/column-editor/column-editor.component.spec.ts --include=projects/praxis-dynamic-form/src/lib/canvas/components/canvas-toolbar/canvas-toolbar.component.spec.ts`
- Schema/layout services: `npx ng test praxis-dynamic-form --watch=false --progress=false --include=projects/praxis-dynamic-form/src/lib/services/dynamic-form-layout.service.spec.ts --include=projects/praxis-dynamic-form/src/lib/services/form-layout.service.spec.ts --include=projects/praxis-dynamic-form/src/lib/praxis-dynamic-form.layout-policy.spec.ts`
- Core layout contracts: `npx ng test praxis-core --watch=false --progress=false --include=projects/praxis-core/src/lib/models/form/form-config.model.spec.ts --include=projects/praxis-core/src/lib/helpers/ensure-ids.helper.spec.ts --include=projects/praxis-core/src/lib/helpers/form-layout-materializer.spec.ts`
- Surface materialization: `npx ng test praxis-core --watch=false --progress=false --include=projects/praxis-core/src/lib/services/surface-open-materializer.service.spec.ts --include=projects/praxis-core/src/lib/widgets/dynamic-widget-loader.directive.spec.ts`
- Authoring document/config editor: `npx ng test praxis-dynamic-form --watch=false --progress=false --include=projects/praxis-dynamic-form/src/lib/praxis-dynamic-form-authoring-protocol.spec.ts --include=projects/praxis-dynamic-form/src/lib/praxis-dynamic-form-widget-config-editor.spec.ts --include=projects/praxis-dynamic-form/src/lib/praxis-dynamic-form.config-editor.spec.ts --include=projects/praxis-dynamic-form/src/lib/config-editor/praxis-dynamic-form-config-editor.spec.ts`
- AI/rule layout authoring: `npx ng test praxis-dynamic-form --watch=false --progress=false --include=projects/praxis-dynamic-form/src/lib/ai/praxis-dynamic-form-authoring-manifest.spec.ts --include=projects/praxis-dynamic-form/src/lib/ai/dynamic-form-rule-authoring-context.spec.ts --include=projects/praxis-dynamic-form/src/lib/ai/dynamic-form-agentic-authoring-turn-flow.spec.ts --include=projects/praxis-dynamic-form/src/lib/utils/rule-authoring-diagnostics.spec.ts`
- Visual blocks: `npx ng test praxis-dynamic-form --watch=false --progress=false --include=projects/praxis-dynamic-form/src/lib/utils/visual-block-rule-content-overrides.util.spec.ts --include=projects/praxis-dynamic-form/src/lib/utils/rule-converters.spec.ts`
- Submit boundary: add `normalize-submit-payload.spec.ts` when layout/visual-block changes could affect payload construction.
- Browser layout: Playwrights such as `projects/praxis-dynamic-form/test-dev/e2e/visual-blocks-responsive-ux.playwright.spec.ts`, `projects/praxis-dynamic-form/test-dev/e2e/form-config-editor-layout.playwright.spec.ts`, and narrow viewport checks when UI layout changed.
- Grouped-command partial-row changes must include core materializer tests for `preserve`, eligible
  widening, fixed/compact exclusions, and deterministic spans; Dynamic Form DOM/diagnostic tests;
  and `schema-layout-policy-demo.playwright.spec.ts` geometry at desktop, tablet, and narrow widths.
- `npm run build:praxis-dynamic-form` when public exports, layout models, config editor, runtime layout services, or generated presets change.
- `npm run validate:published-doc-assets` and `npm run generate:registry:ingestion` when public docs, JSON API docs, or generated AI/registry surfaces change.

## Companion Skills

- Use `praxis-form-schema-runtime-modes` when `layoutPolicy`, generated presets, or presentation mode depend on schema-driven create/edit/view runtime.
- Use `praxis-form-runtime-submit` when layout affects runtime form construction or submit payload boundaries.
- Use `praxis-form-authoring-settings` when layout is edited through config editor, Settings Panel, JSON editor, or apply/save/reset.
- Use `praxis-form-editor-document-roundtrip` when layout changes must persist through `DynamicFormAuthoringDocument` and reopen exactly.
- Use `praxis-form-ai-rules-validation` when layout or visual blocks are authorable by AI/rules.
- Use `praxis-ui-product-design` for visual hierarchy, density, accessibility, and screenshot validation.
- Use `praxis-dynamic-fields-editorial` when field discovery or editor metadata coverage changes.

