DES-374: Add lotus-audit-ios skill — auto-generate iOS Lotus audits against Figma

[OJBoon]

Jira: DES-374 — Lotus Design System (Epic)

Summary

• New Claude Code skill at .claude/skills/lotus-audit-ios/ that generates a fresh iOS Lotus audit on demand: fetches canonical tokens from Figma via figma-ds-cli, diffs against the iOS Swift implementation, scans the iOS app for tokenised vs hardcoded usage, and writes a dated Markdown report into Olly's Obsidian vault.
• Companion scripts/fetch-figma-tokens.mjs walks aliases on the semantic Colour collection and resolves them to primitive hex values per mode.
• flows.yaml maps the 38 folders under parkhub/ios/JustPark/Screens/ into product flows so the report can roll up per-flow as well as per-screen.

How it works

1. Skill prompts the user to confirm the Lotus design system file is the focused tab in Figma Desktop. (Skill never auto-focuses the file — avoids disrupting a full-screen workspace.)
2. fetch-figma-tokens.mjs runs figma-ds-cli eval against the local Figma Desktop CDP port. Returns 137 variables across 4 collections (Colour, Colour (Primitives), Padding, Corner Radius) with values and modes resolved.
3. Skill reads iOS Lotus sources + asset catalog, diffs against Figma, then scans the iOS app for compliance.
4. Output lands at ~/Documents/Olly's Brain/Areas/JustPark/Projects/Lotus/Audits/YYYY-MM-DD — iOS.md.

Why these design decisions

• No Figma REST API — Variables endpoint requires Enterprise plan; JustPark's plan doesn't expose file_variables:read PAT scope.
• No Figma plugin — figma-ds-cli works today, no plugin install/maintenance overhead.
• figma-cli eval not var list — var list only returns names + types; eval returns full structured data including valuesByMode and VARIABLE_ALIAS references.
• Skill prompts for focused-tab confirmation — avoids running figma-cli connect, which auto-focuses Figma and disrupts full-screen workspaces.
• Output to Obsidian vault, not Google Docs — keeps audits versioned alongside the rest of the Lotus project notes; manual paste into a Google Doc is trivial when sharing externally.

Test plan

• node .claude/skills/lotus-audit-ios/scripts/fetch-figma-tokens.mjs /tmp/test.json returns 137 vars (verified locally on 2026-05-07).
• Run /lotus-audit-ios end-to-end with parkhub/ios cloned locally — verify the skill writes a report into the vault and detects known issues (radiusFull = 32 vs 999, h2PoppinsLight = 23pt).
• Re-run after a Figma token change — verify the new value appears in the next audit.

Out of scope (v1)

• Component-level parity (raw Button vs ButtonPrimary etc). Token-level only.
• Web and Android audits. Naming convention leaves room for lotus-audit-android, lotus-audit-web later.
• Push to Google Docs. Markdown-to-vault is the v1 output; Olly pastes into Docs manually if external sharing needed.
• Token suggestion mode (cf. Cut's design-system-manager "suggest"). Pure audit only.

Notes

• The skill works against today's iOS Lotus naming (LotusColours, LotusTypography, etc.) — not the planned LotusColor/LotusFont adapter naming in platforms/ios/DESIGN.md. Will need a small update once the migration lands.
• flows.yaml is editable — adjust as the iOS app evolves. Unmapped folders fall through to "Unmapped" so nothing is silently dropped.

🤖 Generated with Claude Code

[gitstream-cm]

🚨 Warning: Approaching Monthly Automation Limit

Monthly PRs automated: 243/250

Your organization has used over 90% of its monthly quota for gitStream automations. Once the quota is reached, new pull requests for this month will not trigger gitStream automations and will be marked as “Skipped”.

To avoid interruptions, consider optimizing your automation usage or upgrading your plan by contacting LinearB.