fix(docs): align Storybook inventory and design documentation

.storybook/qa/generate-inventory.mjs

@@ -24,7 +24,22 @@ const inventory = files.map(file => {
   return { file: path.relative(root, file).replaceAll('\\', '/'), title, metaTags, stories }
 })
 const all = inventory.flatMap(f => f.stories)
-const summary = { storyFiles: files.length, stories: all.length, categories: Object.fromEntries(['PRIMARY', 'VERIFICATION', 'UTILITY', 'LEGACY / DUPLICATE'].map(c => [c, all.filter(s => s.category === c).length])), decisions: Object.fromEntries(['KEEP', 'HIDE', 'MERGE_CANDIDATE', 'DELETE_CANDIDATE'].map(c => [c, all.filter(s => s.decision === c || s.candidate === c).length])), hierarchy: ['Foundation', 'Components', 'Patterns', 'Center Graphic', 'Theme'] }
+// Top-level groups that actually exist, in the storySort order of .storybook/preview.tsx ("*" = unlisted groups).
+function topLevelHierarchy() {
+  const groups = [...new Set(inventory.map(f => f.title.split('/')[0]))]
+  const source = fs.readFileSync(path.join(root, '.storybook/preview.tsx'), 'utf8').replace(/\/\/.*$/gm, '')
+  const start = source.indexOf('[', source.indexOf('order:'))
+  const order = []
+  for (let i = start, depth = 0; i < source.length; i++) {
+    const ch = source[i]
+    if (ch === '[') depth++
+    else if (ch === ']' && --depth === 0) break
+    else if (ch === '"') { const end = source.indexOf('"', i + 1); if (depth === 1) order.push(source.slice(i + 1, end)); i = end }
+  }
+  const unlisted = groups.filter(g => !order.includes(g)).sort()
+  return order.flatMap(g => g === '*' ? unlisted : groups.includes(g) ? [g] : []).concat(order.includes('*') ? [] : unlisted)
+}
+const summary = { storyFiles: files.length, stories: all.length, categories: Object.fromEntries(['PRIMARY', 'VERIFICATION', 'UTILITY', 'LEGACY / DUPLICATE'].map(c => [c, all.filter(s => s.category === c).length])), decisions: Object.fromEntries(['KEEP', 'HIDE', 'MERGE_CANDIDATE', 'DELETE_CANDIDATE'].map(c => [c, all.filter(s => s.decision === c || s.candidate === c).length])), hierarchy: topLevelHierarchy() }
 const output = path.join(root, '.storybook', 'qa')
 fs.mkdirSync(output, { recursive: true })
 fs.writeFileSync(path.join(output, 'story-inventory.json'), JSON.stringify({ summary, inventory }, null, 2) + '\n')