update-ui-inventory

Update UI Inventory Skill

When to Activate

Activate this skill when:

• Adding new UI components to the engine
• Removing or deprecating components
• The component-inventory CI check fails
• You want to verify docs match the actual component count
• After merging PRs that add/remove components

Files Involved

File	Purpose
.github/component-inventory.json	Source of truth for component counts
docs/design-system/COMPONENT-REFERENCE.md	User-facing component documentation
libs/engine/src/lib/ui/components/	Actual component source files

Inventory Structure

The inventory tracks 13 component categories:

{
	"components": {
		"total": 186,
		"breakdown": {
			"primitives": 45,
			"nature": 64,
			"ui": 29,
			"typography": 11,
			"chrome": 6,
			"terrarium": 7,
			"gallery": 4,
			"charts": 4,
			"content": 4,
			"states": 4,
			"forms": 3,
			"indicators": 3,
			"icons": 2
		}
	}
}

Step-by-Step Process

1. Count Components in Each Category

Run these commands to get actual counts:

# Count .svelte files in each category
for dir in primitives nature ui typography chrome terrarium gallery charts content states forms indicators icons; do
  count=$(find libs/engine/src/lib/ui/components/$dir -name "*.svelte" 2>/dev/null | wc -l | tr -d ' ')
  echo "$dir: $count"
done

2. Compare with Inventory

Read the current inventory and compare:

cat .github/component-inventory.json

3. Identify Discrepancies

Look for:

• New components: Files exist but aren't in the count
• Removed components: Count includes files that no longer exist
• Moved components: Component relocated to different category

4. Update Inventory JSON

Edit .github/component-inventory.json:

{
  "lastUpdated": "YYYY-MM-DD",
  "lastAuditedBy": "claude/<context>",
  "components": {
    "total": <sum of all categories>,
    "breakdown": {
      "<category>": <new count>,
      ...
    }
  }
}

5. Update Component Reference

Edit docs/design-system/COMPONENT-REFERENCE.md:

1. Update the intro line:

   > 186 components organized by category...
   

2. Update Quick Links (the anchor links include counts):

   - [ui/ - Core UI Components](#ui---core-ui-components-29)
   

3. Update section headers:

   ## ui/ - Core UI Components (29)
   

4. Add new component to relevant table (if significant): For Glass components, add to "Other Glass Components" table:

   | `GlassNewComponent` | Description of what it does |
   

5. Update the last updated date at the bottom:

   _Last updated: YYYY-MM-DD_
   

6. Commit Changes

git add .github/component-inventory.json docs/design-system/COMPONENT-REFERENCE.md
git commit -m "docs: update component inventory

- Update <category> count: X -> Y
- Add <ComponentName> to COMPONENT-REFERENCE.md
- Bump total: A -> B"

Quick Reference: Counting Commands

# Single category count
find libs/engine/src/lib/ui/components/ui -name "*.svelte" | wc -l

# List all files in a category (to identify new ones)
ls libs/engine/src/lib/ui/components/ui/*.svelte

# Find Glass components specifically
ls libs/engine/src/lib/ui/components/ui/ | grep -i glass

# Total across all categories
find libs/engine/src/lib/ui/components -name "*.svelte" | wc -l

Documentation Guidelines

When adding components to COMPONENT-REFERENCE.md:

Glass Components (Always Document)

Glass components define Grove's visual language - always add them to the "Other Glass Components" table with a clear description.

Standard Components

Add to the "Standard Components" table if it's a general-purpose wrapper.

Specialized Components

For category-specific components (nature, charts, etc.), add to the appropriate section if it's significant or has unique props worth documenting.

Example: Adding a New Glass Component

After adding GlassStatusWidget.svelte:

1. Count confirms ui went from 28 to 29

2. Update inventory:

   "ui": 29,
   "total": 186,
   "lastUpdated": "2026-01-21"
   

3. Update COMPONENT-REFERENCE.md:

   • Line 3: > 186 components...
   • Line 13: - [ui/ - Core UI Components](#ui---core-ui-components-29)
   • Line 74: ## ui/ - Core UI Components (29)
   • After line 209, add to table:

     | `GlassStatusWidget` | Real-time status widget with auto-refresh |
     

   • Last line: *Last updated: 2026-01-21*

CI Integration

The .github/workflows/component-inventory.yml workflow:

• Runs on PRs touching libs/engine/src/lib/ui/components/**
• Counts actual components vs inventory
• Fails if there's a mismatch
• Provides helpful output showing discrepancies

When CI fails, run this skill to fix the mismatch.

Checklist

Before finishing:

• All category counts match actual file counts
• Total equals sum of all categories
• lastUpdated date is today
• COMPONENT-REFERENCE.md counts match inventory
• New significant components added to appropriate documentation table
• Quick Links anchors updated if section headers changed
• Changes committed with descriptive message