AI exchange package reference

Every exchange file uses:

{
  "format": "skafold-context",
  "version": "1.0",
  "project": {},
  "pages": []
}

Top-level fields

• generator: AI provider, model, skill version, and generation time.
• project: project name, summary, goals, audiences, constraints, and delivery notes.
• pages: site routes or application screens and their page sections.
• globalSections: canonical definitions for every page section plus organisational dividers.
• journeys: focused actor-led paths for meaningful multi-step goals, including optional typed tracking, decision, and note callouts.
• architecture: implementation items and direct relationships.
• design: visual direction, palette, typography, imagery, and system guidance.
• assumptions: interpretations requiring confirmation.
• openQuestions: unresolved decisions that materially affect the project.

IDs and references

Use stable lowercase kebab-case IDs.

• Page parentId values must reference another page.
• Every page section globalSectionId must reference a non-divider item in globalSections.
• Reusable definition groupId values must reference a kind: "separator" item in globalSections.
• Journey step pageId values must reference a declared page.
• Architecture relationships must reference declared architecture items.
• IDs must be unique within their collection.

Preserve existing IDs when revising an exported package. This helps Skafold reuse existing nodes, placements, connectors, Page Hierarchy cards, and shared section references during replacement import.

Section-definition layout hints

Reusable definitions in globalSections may include layout as an abstract structural reference. Use values such as:

• Full width sm, Full width md, Full width lg, Full width xl
• 2 cards row, 3 cards row, 4 cards row, 5 cards row
• 2 columns, 2 columns 1:2, 2 columns 2:1, 2 columns 3:5
• 3 columns, 4 columns, 5 columns
• 2 x 1 grid, 3 x 2 grid, 3 x 5 grid

section.name communicates component purpose. layout should stay purpose-agnostic and only guide density, column or grid count, and rough composition without prescribing exact final UI.

Definition and placement fields

Canonical definitions may include layout, notes, tags, buildGuidance, and their library statusColor. Page placements stay lightweight with id, name, globalSectionId, optional instanceName, and their independent content statusColor.

Definition fields include:

• notes: purpose, content intent, or handoff context.
• tags: composition cues such as hero, conversion, grid with cards, icons, or form.
• buildGuidance: implementation-specific notes when notes and tags are not enough.
• statusColor: explicit planner workflow color (blue, purple, amber, red, or green). Omit it for no status or not started. When revising older JSON, remove legacy gray; Skafold imports it as no explicit status. statusColor and legacy completed are mutually exclusive and must not appear together in an imported section; completed: true imports as green.
• globalSectionId: link to a reusable shared section.

Prefer notes and tags for new handoff context. Use buildGuidance sparingly for details that are explicitly implementation-specific.

Canonical sections

Use globalSections for every page section definition, including definitions currently placed only once.

{
  "globalSections": [
    {
      "id": "top-nav",
      "name": "Top Nav",
      "layout": "Full width sm",
      "notes": "Shared brand and primary navigation.",
      "tags": ["navigation", "reusable"]
    }
  ],
  "pages": [
    {
      "id": "home",
      "name": "Home",
      "sections": [
        {
          "id": "top-nav",
          "name": "Top Nav",
          "globalSectionId": "top-nav"
        }
      ]
    }
  ]
}

The referenced definition is the source of truth for its stable global label, notes, tags, layout, and build guidance. Definition and page-placement workflow statuses are tracked independently. A placement may provide instanceName as a hierarchy label without renaming the definition.

Page hierarchy

Use parentId only for the primary structural parent. Do not connect every page that can navigate to another page. Detailed task flows belong in separate journeys.

[
  { "id": "home", "name": "Home", "path": "/" },
  { "id": "blog", "name": "Blog", "parentId": "home" },
  { "id": "blog-post", "name": "Blog Post", "parentId": "blog" }
]

Design data

Design fields are semantic and import into native Skafold design nodes. Colors must use six-digit hexadecimal values such as #1E1B18.

Omit unsupported or unknown values rather than inventing guidance.