swiftui-design-consultation

/superpowers-gstack:swiftui-design-consultation

Apple-canon design system consultation for SwiftUI projects. Output: DESIGN.md + DesignSystem/ Swift Package + DESIGN.html (via htmlify).

Phase 0 — Setup

Step 0.0: Initialize gstack helpers (set $SLUG)

This skill writes per-project state under ~/.gstack/projects/$SLUG/, so $SLUG (the gstack project identifier derived from the git remote) must be set before any other Phase reads or writes it.

# Pull gstack-slug into the current shell. Sets $SLUG = repo-slug
# from `git remote get-url origin` per gstack convention.
#
# CAREFUL: `eval "$(... 2>/dev/null)" || fallback` does NOT work — if
# gstack-slug is missing, command substitution returns empty, `eval ""`
# succeeds (exit 0), and the fallback never runs. Capture output first
# and check non-empty explicitly.
SLUG_OUTPUT=$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)
if [ -n "$SLUG_OUTPUT" ]; then
  eval "$SLUG_OUTPUT"
fi
if [ -z "${SLUG:-}" ]; then
  # Fallback: derive slug from git toplevel basename, or pwd basename
  # if not in a git repo.
  SLUG="$(basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")"
  export SLUG
fi
if [ -z "$SLUG" ] || [ "$SLUG" = "/" ]; then
  echo "FATAL: could not derive SLUG. Aborting." >&2
  exit 1
fi
mkdir -p ~/.gstack/projects/"$SLUG"
echo "SLUG: $SLUG"

$SLUG is referenced throughout subsequent phases for state-file paths (~/.gstack/projects/$SLUG/design-proposal-{ts}.md, ~/.gstack/projects/$SLUG/swiftui-consultation-state.json, etc.).

Step 0.1: Track self-bootstrap (inline platform-question)

mkdir -p .gstack
if [ ! -f .gstack/track ] || [ -z "$(cat .gstack/track 2>/dev/null | tr -d '[:space:]')" ]; then
  echo "TRACK_MISSING"
else
  echo "TRACK: $(cat .gstack/track | tr -d '[:space:]')"
fi

If output is TRACK_MISSING, ask the platform question inline. Since v2.3.0 there is no separate swiftui-track skill — the platform question lives here (when invoked directly) and in /superpowers-gstack:office-hours-track-aware Phase 3 (when reached via the standard office-hours flow).

AskUserQuestion brief:

D0 — Which platform target does this project ship to?
Project/branch/task: declaring SwiftUI track for direct invocation
ELI10: I need to know iPhone/iPad, Mac, or both — so generated
  Package.swift and design defaults match. The marker is set once
  per project and read by all future swiftui-* skills.
Stakes if we pick wrong: Package.swift declares wrong platforms;
  easy to re-run later. No permanent damage.
Recommendation: iOS only (most common for new projects)
Note: options differ in kind, not coverage — no completeness score.
Pros / cons:
A) iOS only (recommended)
  ✅ Most common case; iPadOS works via iOS target automatically
  ✅ Smallest Package.swift surface
  ❌ No macOS companion — add later by re-running
B) macOS only
  ✅ Menu-bar tools, productivity apps, system utilities
  ✅ Liquid Glass strategy tuned for macOS chrome
  ❌ Narrows reach — no phone/tablet
C) Both iOS + macOS
  ✅ Cross-platform Swift Package; max reach
  ❌ More #if os() surfaces; longer compile times
Net: pick where you'll first ship.

Write the chosen value to .gstack/track:

echo "$CHOICE" > .gstack/track

After write, re-read:

TRACK=$(cat .gstack/track | tr -d '[:space:]')
echo "TRACK: $TRACK"

$TRACK must be one of ios | macos | both to continue. If it is anything else (corrupted marker, user typed invalid value), STOP and report BLOCKED — invalid .gstack/track value.

Step 0.2: Detect project mode

MODE="greenfield"
if find . -maxdepth 3 -type f \( -name "*.xcodeproj" -o -name "Package.swift" -o -name "*.swift" \) 2>/dev/null | head -1 | grep -q .; then
  MODE="existing"
fi
echo "MODE: $MODE"

Step 0.3: Verify MCP surface

Call mcp__swiftui-rag__corpus_info (no arguments). Verify the returned JSON has:

• runtime_version (string, e.g., "1.3.1")
• sample_count (integer, > 0)
• hig_rules (array with at least 11 entries)
• accessibility_rules (array with at least 3 entries)

If any field is missing or the call fails, STOP and report: BLOCKED — swiftui-rag MCP unavailable. Run /sync-gbrain or check pipx install.

Step 0.3.1: Verify MCP parameter schemas (defensive)

Tool NAMES are only half the contract. Before any later phase invokes these tools, verify the actual parameter NAMES match what the plan assumes. The tool schemas are visible in Claude Code's tool list (the same list this skill's frontmatter allowed-tools references). Read them and confirm:

| Tool | Expected primary param | If schema differs, use the actual name | |---|---|---| | mcp__swiftui-rag__index_project | path (string) | Look for repo_path, project_path, dir, etc. | | mcp__swiftui-rag__search_project | query (string) | Look for q, text, pattern | | mcp__swiftui-rag__search_swiftui_corpus | question (string) — verified live | Optional: platform, cluster_tag, hyde_doc, top_k | | mcp__swiftui-rag__swift_typecheck | swift_code (string), target_versions (array of strings) | Verify both names | | mcp__swiftui-rag__review_macos_hig | swift_code (string) | Verify name | | mcp__swiftui-rag__review_liquid_glass | swift_code (string) | Verify name | | mcp__swiftui-rag__review_accessibility | swift_code (string) | Verify name |

If a tool's actual schema differs from the table above, the agent executing this plan should ADJUST its invocations accordingly — do not blindly use the names above if the schema disagrees. This is a runtime-correctness gate; the plan's prose uses the most likely names but the schema is authoritative.

If any tool is missing from the tool list (e.g., MCP server not attached), STOP and report BLOCKED — required MCP tool not available.

Step 0.4: Existing-project indexing

If MODE is existing, call mcp__swiftui-rag__index_project with the repo root path. Cache the returned project ID for Phase 1 lookups.

Step 0.5: Read existing DESIGN.md if present

if [ -f DESIGN.md ]; then
  echo "DESIGN_MD_EXISTS"
fi

If exists, read it. We may be doing a refresh consultation, in which case Phase 3 will surface "keep / replace / refine" choices per pillar.

Phase 1 — Product Context

Single combined AskUserQuestion brief. Three fields (platform is already in .gstack/track, no need to re-ask).

Step 1.1: Pre-fill from project context

If README.md or CLAUDE.md exist, read them and extract: product name, audience, space/industry. Pre-fill the AskUserQuestion with what you found, asking the user to confirm or refine.

If MODE is existing and search_project was indexed, call mcp__swiftui-rag__search_project with these queries:

• "Color extension" — surface existing semantic-color decisions
• "Font.system\|Font.custom" — surface existing typography
• "\.material\|\.glassEffect" — surface existing material usage
• "Color(red:" — flag non-semantic colors (a quality signal)

Cache the counts: N Color extensions, M Font declarations, K material usages, X non-semantic colors flagged. These appear in the Phase 1 prompt.

Step 1.2: Ask the combined Phase 1 question

AskUserQuestion brief:

D1 — Product context for the SwiftUI design system

Project/branch/task: starting design consultation for this $TRACK project
ELI10: I need three things before I can propose a design system:
  what the product IS, what feeling it should evoke (so every later
  design choice serves one anchor), and how strict the HIG conformance
  bar is. The platform is already set ($TRACK from .gstack/track).
Stakes if we pick wrong: a memorable-thing answer that's too vague
  produces a generic-feeling app; a too-loose budget lets POLISH
  findings accumulate; an unclear audience leads to mis-tuned
  defaults (e.g., productivity-app density vs reader-app whitespace).

Field 1 — Product context confirm/refine
[Pre-filled from README/CLAUDE.md if fo