Re-sync Organizer Kit metadata

When to run:

• DS team adds / removes / renames Organizer Kit components
• Variant property changes on Design area / Design note / arrow components
• Quarterly maintenance check (cadence lower than DS V2)

Preconditions

1. DOL's Design Organizer Kit file open in Figma Desktop (file key NxdDuGawc6P4d9ffKCoCZ1)
2. figma-console-mcp Desktop Bridge plugin active
3. Verify: mcp__figma-console__figma_get_status with probe: true returns success: true

Step 1 - Extract component inventory

// Run via figma_execute (paste into MCP tool call)
await figma.loadAllPagesAsync();
const INCLUDED = new Set(["Design Organize Kits", "UX Kits"]);
const components = [], sets = [], errors = [];

function walk(node, page, section) {
  if (node.type === "COMPONENT_SET") {
    let props = [];
    try {
      const pd = node.componentPropertyDefinitions || {};
      props = Object.entries(pd).map(([k, v]) => ({
        name: k, type: v.type, defaultValue: v.defaultValue, options: v.variantOptions || null,
      }));
    } catch (e) { errors.push({ id: node.id, name: node.name, error: String(e).substring(0, 100) }); }
    sets.push({ id: node.id, key: node.key, name: node.name, pageName: page, sectionPath: section,
                variantCount: node.children.length, properties: props, description: node.description || "" });
    return;
  }
  if (node.type === "COMPONENT") {
    if (!(node.parent && node.parent.type === "COMPONENT_SET")) {
      components.push({ id: node.id, key: node.key, name: node.name, pageName: page,
                        sectionPath: section, description: node.description || "" });
    }
    return;
  }
  if ("children" in node) {
    const newSec = node.type === "SECTION" ? (section ? section + " / " + node.name : node.name) : section;
    for (const c of node.children) walk(c, page, newSec);
  }
}
for (const p of figma.root.children) {
  if (!INCLUDED.has(p.name)) continue;
  for (const c of p.children) walk(c, p.name, "");
}
return { fileName: figma.root.name, fileKey: figma.fileKey, extractedAt: new Date().toISOString(),
         includedPages: Array.from(INCLUDED), standaloneCount: components.length,
         componentSetCount: sets.length, errorCount: errors.length,
         components, componentSets: sets, errors };

Expected output: ~30-40 standalone + ~30 sets. Cacheable size (~40KB JSON).

Step 2 - Save output to cache

MCP will either return inline (if small) or save to temp file path (if > token limit).

If inline: copy the result object to cache/organizer-inventory.json.

If saved to temp file:

jq -r '.[0].text' <MCP-OUTPUT-PATH> | jq '.result' > DOL-DS-token/design-guideline/figma-ai/organizer/cache/organizer-inventory.json

Step 3 - Regenerate registries

cd "<workspace-root>"
python3 DOL-DS-token/design-guideline/figma-ai/organizer/tools/extract-organizer-metadata.py

Expected:

✓ component-registry.md (slim INDEX): ~140 lines · 10 categories indexed
✓ components/ : 10 detail files · ~67 total items
✓ components/_index.json: machine catalog

Step 4 - Verify

# Idempotence + orphan check
python3 DOL-DS-token/design-guideline/figma-ai/organizer/tools/extract-organizer-metadata.py --check
# Should print: "OK: 12 files in sync"

Step 5 - Review usage-patterns.md

Organizer generator ONLY regenerates the registry (component inventory). The hand-authored usage-patterns.md does NOT auto-update when Organizer Kit changes.

After re-sync:

• If DS team added a NEW component category → add §N to usage-patterns.md describing when/how to use
• If they renamed Level variants → update §2 Design area hierarchy
• If they added new arrow type → update §3 Flow arrows table
• Otherwise → no usage-patterns edit needed

Step 6 - Commit

git add DOL-DS-token/design-guideline/figma-ai/organizer/component-registry.md
git add DOL-DS-token/design-guideline/figma-ai/organizer/components/
# cache/ is gitignored
git commit -m "chore(organizer): resync from Organizer Kit"

Troubleshooting

Symptom	Cause	Fix
figma_execute times out	Too many nodes walked	Narrow INCLUDED set to specific page temporarily
Category slugs changed after regen	New Figma section name not mapped	Update SECTION_TO_CATEGORY in generator + regen
--check passes but usage-patterns feels outdated	Generator doesn’t touch usage-patterns	Manual review; usage-patterns is hand-authored
Organizer cache missing error	Cache file absent or in wrong path	Re-run Step 2 extraction + verify path figma-ai/organizer/cache/organizer-inventory.json

Related

• extract-organizer-metadata.py - generator
• ../usage-patterns.md - hand-authored canvas rules (NOT auto-regenerated)
• ../README.md - folder overview
• ../../tools/resync-figma.md - parallel runbook for DS V2 file (same pattern)