Troubleshooting imports

The file is rejected

Confirm that:

• The file is valid JSON.
• format is exactly skafold-context.
• version is exactly 1.0.
• project.name and project.summary are present.
• pages is an array.
• IDs are unique.
• References point to declared IDs.
• The file is below the import size limit.

Ask the installed Skafold Project Importer or standalone skill to run its validator and return the complete corrected project import file.

A category did not create a node

Skafold omits empty optional categories. Inspect the JSON and confirm that the relevant field contains a non-empty value.

Design categories use fields such as colors, typography, layoutPrinciples, imageryGuidance, motionGuidance, uiTreatment, avoid, and designSystemNotes.

The structure has too many connections

Use parentId only for direct page hierarchy. Remove legacy leadsTo fields and represent detailed task flows as separate journeys.

A replacement removed project content

Replacement imports a complete package, not a patch. The AI must use the exported Skafold JSON as its baseline and retain supported fields that were not changed.

Recover from a previously exported JSON file, then repeat the revision with:

Return the complete revised package. Preserve all existing supported fields and IDs unless this request explicitly changes them. Preserve each page section's page-specific `instanceName`, including when other fields on that page change.

A replacement duplicated nodes or moved the canvas

Skafold tries to reuse matching nodes, connector paths, and Page Hierarchy card positions during replacement import. It works best when unchanged IDs are preserved.

If nodes duplicate or placements reset, repeat the revision from a fresh Skafold export and tell the AI:

Preserve IDs for unchanged pages, sections, globalSections, journeys, architecture items, and design records. Do not rename IDs just because labels changed. Preserve each page section's page-specific instanceName, including when other fields on that page change. Preserve globalSectionId, layout, tags, buildGuidance, and explicit statusColor values unless explicitly changed. Remove legacy `statusColor: "gray"`; an omitted status means not started. Legacy `completed: true` values remain compatible and represent green.

If a page or shared section was intentionally deleted, it should be absent from the revised complete package.

Shared sections did not update everywhere

Confirm that repeated sections use globalSectionId and that the referenced ID exists in top-level globalSections.

New sections are reusable by default. Reuse the same globalSectionId for repeated components, keep shared context on the matching globalSections definition, and use instanceName only for a page-specific placement title. Older embedded sections remain visible as Legacy content until they are replaced or re-imported through the reusable model.

Colors are missing

Each color requires a name and a six-digit hex value.

{
  "name": "--color-accent",
  "value": "#A44E2B"
}

Three-digit hex, RGB, HSL, and named CSS colors are not accepted by the current exchange contract.

You still need help

Include the validation message and a reduced example package when you contact support. Do not include secrets, credentials, private customer data, or production access tokens.