Import an AI-planned project

Skafold Project Importer turns a user's planning conversation with an AI into a complete skafold-context JSON file. Upload that file to create a project in Skafold. This is separate from Skafold Context Exporter, which creates the Markdown handoff package used by IDEs after planning.

Create a new project

1. Open the Skafold dashboard.
2. Choose the AI context import action.
3. Select the generated .json file.
4. Review validation errors or warnings.
5. Confirm the import.

Skafold creates editable nodes for project context, route structure, Page Hierarchy, user journeys, architecture, and design guidance.

Imported pages are available immediately in Page Hierarchy. Skafold creates visible Structure route nodes and hidden Page Hierarchy route-card copies that carry the page's section metadata, route path, and source route link.

Import an existing project update

Use Import/Export JSON when an AI has revised JSON exported from the current project.

1. Open the project in Structure Studio.
2. Open the context menu and choose Import/Export JSON.
3. Download the current JSON and copy the AI revision prompt if you have not already done so.
4. Select the complete revised package.
5. Review validation, change counts, multi-area warnings, and removals.
6. Choose Apply Update.

The update applies a complete project package. Skafold records recent JSON updates in Import History so you can roll back if needed.

When applying an update to an existing project, Skafold tries to preserve existing node IDs, page positions, Page Hierarchy card positions, and connector paths for matching items. This reduces duplicate nodes and layout resets when an AI-edited package is based on the current export.

The match is strongest when the AI preserves IDs. Ask for that explicitly.

Use the exported Skafold JSON as the baseline. Preserve IDs and supported fields, including notes, for unchanged pages, sections, globalSections, journeys, architecture items, and design guidance. Preserve each page section's page-specific instanceName, including when other fields on that page change. Return one complete package, not a patch.

Skafold exports may include an opaque top-level `canvas` snapshot. Keep it unchanged while revising the semantic fields. Skafold restores it for an unchanged round trip and automatically ignores it when the editable project content changes.

Shared sections on import

Packages define every section in globalSections. Every page section is a lightweight placement that references one with globalSectionId.

On import:

• All definitions are stored in the Sections library, including definitions currently placed once.
• Referenced page sections display their library link in Page Hierarchy.
• Page sections reference library entries with globalSectionId; instanceName can provide a page-specific hierarchy label without renaming the reusable definition.
• Editing a reusable definition's name, notes, tags, layout, or build guidance updates referenced instances.
• Reusable-definition and page-instance workflow status colors are independent.
• Divider rows use kind: "separator"; grouped definitions reference the divider with groupId.

Validation warnings

A warning does not always block import. For example, Skafold may warn that a page has no sections. Errors must be corrected before import and usually identify an invalid field, duplicate ID, or missing reference.

Expected design nodes

Each populated design category imports as its own node:

• Direction
• Colors
• Reference
• Typography
• Layout
• Imagery
• Motion
• UI Treatment
• Avoid
• Design System

Empty categories are omitted.