# VIXNODE Page and Layout Creation Instructions
Use these instructions when an AI assistant creates or updates pages through VIXNODE. They define how to choose a page type, preserve layout relationships, construct placeholder HTML, validate a preview, and execute only after confirmation.
## Non-Negotiable Rules
1. Determine the correct `pageType` before generating HTML.
2. Retrieve the current project and relevant page or layout data before using any existing ID.
3. Never guess, invent, or reuse an unrelated `project_id`, `page_id`, `layout`, or `data-nodeid`.
4. Keep project IDs, layout page IDs, and placeholder node IDs separate. They are not interchangeable.
5. For `childLayout` and `layoutPage`, every direct top-level HTML element must have the exact class `app-place-holder`. For `layout`, output a complete HTML document and use `.app-place-holder` only for descendant-fillable slots.
6. For `layout`, return a complete HTML document including ``, ``, ``, and ``. For `childLayout` and `layoutPage`, return an HTML fragment and do not add ``, ``, ``, or an outer page container.
7. In `layout`, shared CSS, scripts, metadata, header, navigation, footer, and other document-level markup may appear normally in the complete HTML document. In `childLayout` and `layoutPage`, do not place `
...shared document structure...
```
A main layout may contain normal document-level and shared site markup such as:
- `` metadata;
- global CSS and design tokens;
- shared scripts when permitted;
- site header;
- navigation;
- shared footer;
- persistent accessibility UI;
- shared language or utility controls;
- fixed structural wrappers;
- descendant-fillable `.app-place-holder` slots.
The main layout MUST NOT wrap the entire document in `.app-place-holder`. Only regions intended to be filled or subdivided by descendant layouts/pages should be placeholders.
A main `layout` MUST contain **at least one** descendant-fillable `.app-place-holder`. It MAY contain multiple placeholders when the site shell exposes multiple independent fillable regions. A `layout` with zero placeholders is invalid.
Every placeholder created by the main layout MUST use:
```text
data-layout = NEW_LAYOUT_PAGE_ID
data-label = NON_EMPTY_PRIMARY_PURPOSE_LABEL
```
and every main-layout slot MUST have its own unique new `data-nodeid`.
Each new main-layout placeholder MUST be empty when created (no text, comments, or nested non-placeholder content).
Canonical shape:
```text
├─
│ ├─ metadata
│ ├─ global CSS
│ └─ shared resources
└─
├─ shared header / navigation
├─ normal shared wrappers
├─ app-place-holder
│ data-layout = MAIN_LAYOUT_PAGE_ID
│ data-nodeid = NEW_GUID_A
│ data-label = NON_EMPTY_SLOT_PURPOSE_A
├─ optional additional shared structure
├─ app-place-holder
│ data-layout = MAIN_LAYOUT_PAGE_ID
│ data-nodeid = NEW_GUID_B
│ data-label = NON_EMPTY_SLOT_PURPOSE_B
└─ shared footer
```
Valid example:
```html
VIXNODE
```
Forbidden for `layout`:
- returning only a placeholder fragment instead of a complete document;
- omitting ``, ``, or ``;
- using `project_id` as `data-layout`;
- reusing unrelated node IDs;
- using another layout's `page_id` for newly created slots;
- converting shared header/footer/navigation into page-specific content slots without reason;
- placing page-specific article/category content directly into the main shared layout.
## Main Layout Generation Rules
The main layout defines shared site chrome and stable document structure. Before generating it, classify content into two groups.
### Shared structure — belongs in `layout`
Examples:
- `` / `` / ``;
- viewport and shared metadata;
- global CSS and design tokens;
- shared header and navigation;
- global footer;
- shared accessibility controls;
- language switcher or utility controls;
- shared wrappers needed across descendant pages;
- stable site-wide scripts when allowed.
### Descendant content — belongs in placeholders
Examples:
- article body;
- page hero content;
- category-specific content;
- page-specific sidebar;
- page-specific related content;
- page-specific media;
- page-specific CTA blocks;
- content that varies between descendant pages.
Create a placeholder only when a descendant layout or page is expected to fill or subdivide that region. Do not create placeholders for every shared element. However, a main `layout` MUST expose at least one descendant-fillable placeholder. One placeholder is the minimum, not the maximum; create multiple placeholders whenever the layout intentionally exposes multiple independent fillable regions.
## `childLayout` Fragment Contract
Use `pageType: "childLayout"` when creating a reusable descendant layout that inherits an existing parent layout.
Required request fields:
- `project_id`
- `name`
- `pageType: "childLayout"`
- `page_id`: a new unique child-layout GUID
- `layout`: the existing parent layout page ID
- `html`
- `fileName` when applicable
The `html` field MUST be an HTML fragment whose direct root elements are exclusively `.app-place-holder` elements. Do not include ``, ``, ``, ``, or an ordinary wrapper.
Before generation, retrieve the parent layout's latest HTML and exact slot topology. Never construct a child layout from remembered or guessed IDs.
An inherited parent placeholder MUST preserve exactly its original `data-layout`, `data-nodeid`, `data-label`, and relative topology. Newly introduced child-owned placeholders MUST use the new child layout `page_id` as `data-layout`, new unique GUIDs as `data-nodeid`, and a non-empty `data-label`.
Each new child-owned placeholder MUST be empty when created (no text, comments, or nested non-placeholder content).
A `childLayout` MUST introduce **at least one new child-owned** `.app-place-holder` inside the appropriate inherited parent slot. It MAY introduce multiple child-owned placeholders. A `childLayout` that merely reproduces the parent slot without defining any child-owned placeholder is invalid.
Canonical shape:
```text
ROOT
└─ inherited parent app-place-holder
data-layout = PARENT_LAYOUT_PAGE_ID
data-nodeid = EXISTING_PARENT_NODE_ID
data-label = EXISTING_PARENT_LABEL
├─ child-owned app-place-holder
│ data-layout = CHILD_LAYOUT_PAGE_ID
│ data-nodeid = NEW_GUID_A
│ data-label = NON_EMPTY_CHILD_SLOT_PURPOSE_A
└─ child-owned app-place-holder
data-layout = CHILD_LAYOUT_PAGE_ID
data-nodeid = NEW_GUID_B
data-label = NON_EMPTY_CHILD_SLOT_PURPOSE_B
```
Valid example:
```html
```
## `layoutPage` Fragment Contract
Use `pageType: "layoutPage"` for actual page content rendered through an existing main or child layout.
Required request fields:
- `project_id`
- `name`
- `pageType: "layoutPage"`
- `layout`: the selected existing main or child layout page ID
- `html`
- `fileName` when applicable
The `html` field MUST be an HTML fragment whose direct roots are existing `.app-place-holder` slots copied from the selected layout. A `layoutPage` MUST NOT create new placeholders or new `data-nodeid` values, and MUST preserve existing `data-label` values.
`data-layout`, `data-nodeid`, and `data-label` apply only to `.app-place-holder` slot elements. Non-placeholder content elements inside slots (for example ``, ``, `
`, `
`) MUST NOT include these attributes. `data-label` remains hidden metadata and does not display as page text.
Hard rule:
```text
NEW placeholder = FORBIDDEN
NEW data-nodeid on slot elements = FORBIDDEN
NEW data-label on slot elements = FORBIDDEN (preserve existing value)
Identity attributes on non-placeholder content elements = FORBIDDEN
```
Canonical shape:
```text
ROOT
├─ existing selected-layout slot
└─ existing selected-layout slot
```
Example:
```html
Article title
Article content.
```
## Page-Type Output Matrix
| `pageType` | HTML type | Root rule | New `page_id` | `layout` required | New `data-nodeid` |
| --- | --- | --- | --- | --- | --- |
| `page` | Normal HTML fragment | Normal HTML allowed | No | No | No |
| `layout` | Complete HTML document | Normal document structure; **1 or more** fillable placeholders required; new slots must be empty and include `data-label` | Yes | No | Yes, for new layout slots |
| `childLayout` | Placeholder fragment | Direct roots must be `.app-place-holder`; **1 or more new child-owned placeholders required**; new child slots must be empty and include `data-label` | Yes | Yes | Child slots only |
| `layoutPage` | Existing placeholder fragment | Direct roots must be `.app-place-holder` | No | Yes | Never |
| `template` | Reusable HTML fragment | Normal fragment allowed | No | No | No |
## CSS and Script Contract
For `layout`, shared `Shared header"
}
```
## 4. Child Layout
Use `childLayout` when a layout must inherit a parent layout and subdivide one or more parent slots into child-owned content slots.
Required fields:
- `project_id`
- `name`
- `pageType: "childLayout"`
- `page_id`: a new GUID for the child layout
- `layout`: the existing parent layout page ID
- `html`
Rules:
- Retrieve the parent layout's latest HTML before building the child layout.
- Preserve the parent placeholder topology. Do not flatten, reorder, rename, or replace parent slots unless the current parent structure explicitly permits it.
- A parent-owned placeholder must retain its original `data-layout`, `data-nodeid`, and `data-label`.
- Place newly introduced child placeholders inside the appropriate inherited parent slot.
- The child layout MUST introduce at least one new child-owned `.app-place-holder`; a child layout with zero new child-owned placeholders is invalid.
- The child layout MAY introduce multiple child-owned placeholders when multiple descendant-fillable regions are needed.
- Every new child-owned placeholder must use the child layout's `page_id` as `data-layout`, a new unique GUID as `data-nodeid`, and a non-empty `data-label`.
- Every new child-owned placeholder must be empty when created (no text, comments, or nested non-placeholder content).
- The direct top-level roots must still be `.app-place-holder` elements. In the common single-slot parent layout, the inherited parent slot is the sole top-level element and the child-owned slots are nested inside it.
- Do not use `project_id` as either the parent `layout` ID or the child layout `page_id`.
```json
{
"project_id": "project-id",
"name": "Article Child Layout",
"pageType": "childLayout",
"page_id": "b9a5d3f5-d989-4e84-bacd-27ed011afd3b",
"layout": "f8266c00-69e4-4a4a-b1c7-a90c03814b56",
"fileName": "layout-article",
"html": "
"
}
```
The nesting in this example is intentional: the parent-owned slot remains the top-level element, while the new article slots belong to the child layout.
## 5. Page Using a Layout
Use `layoutPage` for content rendered through an existing main layout or child layout.
Required fields:
- `project_id`
- `name`
- `pageType: "layoutPage"`
- `layout`: the selected main or child layout page ID
- `html`
Rules:
- A `layoutPage` does not own or create placeholders.
- Retrieve the selected layout's latest HTML and slot definitions first.
- Include only the existing slots that the page is expected to fill.
- Copy each selected placeholder's `data-layout`, `data-nodeid`, and `data-label` exactly.
- Do not generate new placeholder IDs.
- Every direct top-level element in the submitted fragment must be an `.app-place-holder`.
- Put page content and optional page-specific CSS inside the matching placeholders.
- Do not submit a complete HTML document or ordinary full-page wrapper with `pageType: "layoutPage"`.
### Page using a main layout
```json
{
"project_id": "project-id",
"name": "Landing Page",
"pageType": "layoutPage",
"layout": "f8266c00-69e4-4a4a-b1c7-a90c03814b56",
"fileName": "landing",
"html": "
"
}
```
## 6. Reusable Template
Use `template` for reusable fragments such as navigation, footer, hero, card, or content sections.
Required fields:
- `project_id`
- `name`
- `pageType: "template"`
- `html`
The `layout` field is not required.
```json
{
"project_id": "project-id",
"name": "Navigation Template",
"pageType": "template",
"fileName": "nav-template",
"html": ""
}
```
## Internal Page Links
For creation and modification, internal links within the current project MUST use relative paths without a leading `/`. A root-relative URL such as `/about` resolves against the shared hosting domain root and loses the project's publication prefix. Do not add a `` that causes the same problem.
- Resolve destinations from existing or approved pages and their actual `virtualPath` plus `fileName`; do not invent routes or append `.html` unless the returned published URL uses it.
- From a page in the project root, use `index`, `about`, `contact`, or `products/detail` for those respective destinations.
- From `products/detail`, use `../about` to reach the root-level `about` page, and `other` to reach `products/other`. Calculate the relative path from the rendered page URL, including for shared navigation inherited from a layout.
- Preserve fragment links (`#section`), external absolute URLs, `mailto:`, and `tel:` links. Do not strip leading slashes from unrelated asset or API URLs.
- When modifying navigation or page links, inspect existing internal links for domain-root paths and correct affected links to project-relative destinations before previewing.
## Validation Checklist
Before generating a preview, verify all of the following:
- [ ] Internal page links have no leading `/` and resolve to the intended page from its actual rendered path.
- [ ] `project_id` was retrieved from the current project list.
- [ ] `pageType` matches the intended operation.
- [ ] A new `layout` or `childLayout` has a new, unique `page_id` GUID.
- [ ] `layout` points to an existing page of the expected layout type.
- [ ] The latest selected layout HTML was retrieved before copying its slots.
- [ ] For `layout`, the HTML is a complete document with ``, ``, ``, and ``.
- [ ] For `layout`, at least one descendant-fillable `.app-place-holder` exists; multiple placeholders are allowed.
- [ ] For `childLayout`, at least one new child-owned `.app-place-holder` exists; multiple child-owned placeholders are allowed.
- [ ] For `childLayout` and `layoutPage`, every direct top-level element is `.app-place-holder`.
- [ ] For `childLayout` and `layoutPage`, no ``, ``, ``, ``, standalone `