swiftui-design-consultation
Apple-canon design system for SwiftUI projects: writes DESIGN.md plus a DesignSystem Swift Package, then runs a HIG-budgeted native review. Use when starting or refreshing a SwiftUI design system.
SKILL.mdskills/swiftui-design-consultation/SKILL.md
GitHub/superpowers-gstack:swiftui-design-consultation
Apple-canon design system consultation for SwiftUI projects. Output:
DESIGN.md + DesignSystem/ Swift Package, reviewed against a HIG
conformance budget. The proposal is previewed as an Artifact page before
approval; DESIGN.md itself is the committed artefact — no DESIGN.html
is generated or committed. templates/ and bin/ live NEXT TO this
SKILL.md, not in the user's project: set SKILL_DIR to this skill's base
directory (shown when the skill loads) and address assets as $SKILL_DIR/….
Phase 0 — Setup
Step 0.0: Initialize gstack helpers (set $SLUG)
Per-project state lives under ~/.gstack/projects/$SLUG/, so $SLUG
(the gstack project identifier derived from the git remote) is set first.
SLUG_OUTPUT=$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)
[ -n "$SLUG_OUTPUT" ] && eval "$SLUG_OUTPUT"
if [ -z "${SLUG:-}" ]; then
# Fallback: git toplevel basename, or pwd basename outside a 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"
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 (the standard
flow asks it in /superpowers-gstack:office-hours-track-aware):
D0 — Which platform target does this project ship to?
ELI10: iPhone/iPad, Mac, or both — so the generated Package.swift and
design defaults match. Set once per project; read by all swiftui-* skills.
Stakes if we pick wrong: wrong platforms in Package.swift; easy to re-run.
Recommendation: iOS only (most common for new projects)
A) iOS only (recommended) — iPadOS comes with the iOS target; smallest surface
B) macOS only — menu-bar tools, productivity apps, system utilities
C) Both iOS + macOS — max reach; more #if os() surfaces, longer compiles
Write the chosen value (ios, macos or both) and re-read it:
echo "$CHOICE" > .gstack/track
TRACK=$(cat .gstack/track | tr -d '[:space:]')
echo "TRACK: $TRACK"
$TRACK must be ios, macos or both; otherwise STOP: 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). The returned JSON
must have runtime_version (string), sample_count (> 0), hig_rules
(≥ 11 entries) and accessibility_rules (≥ 3 entries). Otherwise STOP:
BLOCKED — swiftui-rag MCP unavailable. Run /sync-gbrain or check pipx install.
Before calling any other mcp__swiftui-rag__* tool, load its schema via
ToolSearch and use the parameter names it reports.
Step 0.4: Existing-project indexing
If MODE is existing, call mcp__swiftui-rag__index_project with the
repo root path and keep the returned project ID for Phase 1.
Step 0.5: Read existing DESIGN.md if present
If DESIGN.md exists, read it: this is a refresh consultation, and
Phase 2 will offer keep / replace / refine per pillar.
Phase 1 — Product Context
One combined AskUserQuestion brief with three fields. Platform is already
in .gstack/track; do not re-ask.
Step 1.1: Pre-fill from project context
If README.md or CLAUDE.md exist, read them and extract product name,
audience and space/industry to pre-fill the brief.
If MODE is existing, call mcp__swiftui-rag__search_project with
"Color extension", "Font.system\|Font.custom",
"\.material\|\.glassEffect" and "Color(red:" (non-semantic colors, a
quality signal). Cache the counts: N Color extensions, M Font declarations, K material usages, X non-semantic colors flagged.
Step 1.2: Ask the combined Phase 1 question
D1 — Product context for the SwiftUI design system
ELI10: I need what the product IS, what feeling it should evoke (one
anchor every later choice serves), and how strict the HIG bar is.
Stakes if we pick wrong: a vague memorable-thing gives a generic app; a
loose budget lets POLISH findings pile up; an unclear audience mis-tunes
defaults (productivity density vs reader whitespace).
Field 1 — Product context confirm/refine [pre-filled if found]
Field 2 — Memorable Apple thing: "What's the one Apple-native quality this
app should be remembered for after first launch?" One sentence, e.g.
"as fluid as Things", "as sharp as Linear-mac", "as quiet as Reeder".
Field 3 — HIG conformance budget
A) Recommended: 0 CRITICAL · 0 SIGNIFICANT · ≤5 POLISH
B) Strict: 0 / 0 / 0 (must feel Apple-native on first launch)
C) Relaxed: 0 / 3 / 10 (early prototype)
If MODE is existing, prepend: I indexed your project. Current patterns: $N Color extensions, $M Font declarations, $K material usages, $X non-semantic colors flagged. We can keep, replace, or refine each.
Step 1.3: Store the answer
Cache the answers in ~/.gstack/projects/$SLUG/swiftui-consultation-state.json
with keys track, product_context, memorable_thing, budget
(critical/significant/polish), mode, existing_patterns. This
state survives /clear, so a long consultation can resume.
Phase 2 — Proposal (Artifact preview + approval)
Step 2.1: Ground each pillar in the corpus
Query mcp__swiftui-rag__search_swiftui_corpus per pillar, passing
platform from $TRACK: Typography "typography roles SF Pro semantic font", Color "semantic color asset catalog dark mode adaptive",
Materials "Liquid Glass material chrome content layer", Motion "spring animation snappy smooth named easing", Accessibility "VoiceOver Dynamic Type contrast accessibility". Each returns 3–5 corpus samples plus
HIG-page citations; they ground every proposed choice.
Step 2.2: Write the proposal as Markdown
TS=$(date +%Y%m%d-%H%M%S)
PROPOSAL_PATH=~/.gstack/projects/"$SLUG"/design-proposal-"$TS".md
Write $PROPOSAL_PATH directly as Markdown. It is the single source of
truth: Phase 3 fills both DESIGN.md and the Swift templates from it, so
every section must carry concrete, named values — not only prose.
- H1
Design Proposal: $PRODUCT_NAME, then a metadata line with date, track, product context, memorable thing and aesthetic direction. - H2 per pillar, each with rationale, HIG citation links and a table of
choices: Typography (roles →
Font.TextStyle), Color (brand hex values with light/dark backgrounds; semantic → system colors), Materials (where glass goes / doesn't), Spacing & Radii (named point constants), Motion (named presets with spring parameters), Accessibility, Platforms (per-track assertions). - H2 HIG Conformance Budget (the Phase 1 numbers) and H2 Decisions Log (one bullet per decision with its reason).
In refresh mode, mark each pillar keep / replace / refine against
the existing DESIGN.md.
Step 2.3: Preview and ask approve / drill / change
Publish the proposal as a page with the Artifact tool (load the
artifact-design skill first) so the user reads it before approving:
typography specimens, color swatches in light and dark, material
placement, motion presets, budget panel and decisions log. Give the user
the link, then ask:
D2 — Does the proposed design system look right?
ELI10: The proposal page is published; pick approve, drill, change or restart.
A) Approve — write DESIGN.md + Swift Package now (recommended if it feels right)
B) Drill into [pillar] — tighten one pillar without committing the others
C) Change [pillar] — different direction for one pillar
D) Start over — rebuild the whole proposal with different constraints
If A: proceed to Phase 3. If B or C: ask which pillar, re-query
that pillar's corpus, rewrite that section, republish the same page, loop
back to D2. If D: go back to Phase 1.
Step 2.4: Cache the approved proposal
cp "$PROPOSAL_PATH" ~/.gstack/projects/"$SLUG"/swiftui-consultation-state.proposal.md
Phase 3 reads this copy; the timestamped file stays as the audit trail.
Phase 3 — Write Artefacts (with native-review chain)
Both DESIGN.md and DesignSystem/* are filled from the cached proposal,
so prose and Swift declarations name the same roles, colors and presets.
If the proposal's track differs from $TRACK, STOP and AskUserQuestion
which is authoritative.
Step 3.1: Generate DESIGN.md from template (with overwrite safety)
PROPOSAL=~/.gstack/projects/"$SLUG"/swiftui-consultation-state.proposal.md
[ -f "$PROPOSAL" ] || { echo "ERROR: no cached proposal — Phase 2 must complete first."; exit 1; }
if [ -f DESIGN.md ]; then
BACKUP="DESIGN.md.backup-$(date +%Y%m%d-%H%M%S)"
cp DESIGN.md "$BACKUP"
echo "Existing DESIGN.md backed up to $BACKUP"
fi
Read $SKILL_DIR/templates/DESIGN.md.template and substitute every
{{TOKEN}} from the matching proposal section: {{DATE}},
{{PRODUCT_CONTEXT}}, {{MEMORABLE_THING}}, {{AESTHETIC_DIRECTION}}
from the metadata line; the seven {{*_PROSE}} tokens from the pillar
sections; {{BUDGET_CRITICAL}}, {{BUDGET_SIGNIFICANT}},
{{BUDGET_POLISH}} from the budget section; {{DECISIONS_LOG}} as the
bulleted list. Write to <repo>/DESIGN.md. Never leave a token
unresolved or substitute an empty string — a missing value means the
proposal is incomplete; return to Phase 2 for that pillar.
Step 3.2: Generate the Swift Package (with overwrite safety)
if [ -d DesignSystem ]; then
BACKUP_DIR="DesignSystem.backup-$(date +%Y%m%d-%H%M%S)"
mv DesignSystem "$BACKUP_DIR"
echo "Existing DesignSystem/ moved to $BACKUP_DIR"
fi
mkdir -p DesignSystem/Sources/DesignSystem/Resources DesignSystem/Tests/DesignSystemTests
Read each template under $SKILL_DIR/templates/, substitute its tokens
from the proposal, and write it to the mapped path under DesignSystem/:
| Template | Output path | Tokens (proposal section) |
|---|---|---|
Package.swift.template |
Package.swift |
{{PLATFORMS}} (from $TRACK) |
Colors.swift.template |
Sources/DesignSystem/Colors.swift |
{{BRAND_COLORS}}, {{SEMANTIC_COLORS}} (Color) |
Typography.swift.template |
Sources/DesignSystem/Typography.swift |
{{TYPE_ROLES}} (Typography) |
Spacing.swift.template |
Sources/DesignSystem/Spacing.swift |
{{SPACING_CONSTANTS}}, {{RADIUS_CONSTANTS}} (Spacing & Radii) |
Motion.swift.template |
Sources/DesignSystem/Motion.swift |
{{MOTION_PRESETS}} (Motion) |
Materials.swift.template |
Sources/DesignSystem/Materials.swift |
none |
HIGBudgetTests.swift.template |
Tests/DesignSystemTests/HIGBudgetTests.swift |
none |
PlatformsTests.swift.template |
Tests/DesignSystemTests/PlatformsTests.swift |
{{DECLARED_TRACK}}, {{PLATFORM_ASSERTIONS}} (Platforms) |
{{PLATFORMS}} per $TRACK: ios → .iOS(.v26), macos →
.macOS(.v26), both → .iOS(.v26), .macOS(.v26). Render brand colors
as Color extensions backed by color sets under
Sources/DesignSystem/Resources/Assets.xcassets/ (light, dark and
high-contrast variants), semantic colors as extensions onto system
colors, motion presets as static let X: Animation, spacing and radii as
static let X: CGFloat, platform assertions as #if os(...) test guards.
WCAG contrast check. For each brand hex, run
$SKILL_DIR/bin/contrast-check.sh once against the proposed light
background and once against the dark background:
if RESULT=$("$SKILL_DIR/bin/contrast-check.sh" "$BRAND_HEX" "$BG_HEX" 2>&1); then
PASS=$(echo "$RESULT" | grep -o '"pass_aa_normal": [a-z]*' | awk '{print $2}')
else
PASS="error"; echo "WARN: contrast-check failed for $BRAND_HEX vs $BG_HEX" >&2
fi
If PASS is error (likely bc missing or invalid hex), ask the user
whether to accept the color without a verified contrast; never treat an
empty result as a pass. If PASS is false, report the ratio from the
JSON, flag which background fails WCAG AA, and AskUserQuestion: keep the
hex (override) or pick another. The skill does not auto-adjust colors.
Step 3.3: Type-check the generated Swift
Call mcp__swiftui-rag__swift_typecheck on the generated code with
target versions per $TRACK: ios → ["iOS-26.0"], macos →
["macOS-26.0"], both → both. On failure, fix the offending file
(usually a missing #if os() guard) and retry; hard cap 3 attempts, then
STOP and report the diagnostic.
Step 3.4: Native review, one fix pass, one re-run
Run the review chain once, fix CRITICAL findings, re-run once, and report what remains against the budget.
Spec-level review (DESIGN.md). Read DESIGN.md into context, then
invoke the merged native review with the platform from .gstack/track:
Read(file_path="<absolute path>/DESIGN.md")
Skill(skill="superpowers-gstack:apple-native-review",
args="platform=$TRACK. Review the DESIGN.md just loaded into context: the design system spec for a SwiftUI project; budget is $BUDGET_CRITICAL/$BUDGET_SIGNIFICANT/$BUDGET_POLISH.")
Capture its verdict and findings by severity (CRITICAL, SIGNIFICANT, POLISH).
Code-level review (each .swift under DesignSystem/Sources/DesignSystem/).
The tools are complementary; run them in parallel per file with the same
swift_code argument — but only the ones that match $TRACK:
| Tool | Rules | Runs when |
|---|---|---|
mcp__swiftui-rag__review_macos_hig |
full macOS HIG ruleset (C1, C2, S1–S9) | macos or both — never on an ios track: its menu-bar and window findings would be fed into the fix pass and steer the proposal toward the wrong platform |
mcp__swiftui-rag__review_accessibility |
A1–A3 | always |
mcp__swiftui-rag__review_liquid_glass |
Liquid Glass subset (C1, S7, S8) | always |
Aggregate all findings, spec-level and code-level, deduplicated by
(rule_id, file:line) — the Liquid Glass tool repeats a subset of the
HIG tool's findings; count each once.
Fix pass. For every CRITICAL finding: edit the cached proposal
Markdown (the single source of truth — never patch DESIGN.md or
DesignSystem/* directly), regenerate from Step 3.1 onwards, type-check
again, then re-run the spec-level and code-level reviews exactly once.
Report. Compare the re-run counts with the Phase 1 budget. Within
budget: continue to Step 3.5 and print DESIGN.md + DesignSystem/ committed. 0 CRITICAL · 0 SIGNIFICANT · 3 POLISH (within budget of 0/0/5).
Over budget: list the remaining findings ranked by severity with
file:line and a proposed fix, then AskUserQuestion (A) ship anyway, (B) override the budget to the actual numbers, (C) refine manually now;
only A and B continue to Step 3.5.
Step 3.5: Commit (including the .gstack/track marker)
.gstack/track is a project-level decision and ships in the repo. If the
project ignores .gstack/, force-add the marker and record an exception
so future runs don't silently drop it:
if git check-ignore -q .gstack/track 2>/dev/null; then
grep -q '^!\.gstack/track$' .gitignore 2>/dev/null || echo '!.gstack/track' >> .gitignore
git add .gitignore
git add -f .gstack/track
else
git add .gstack/track
fi
git add DESIGN.md DesignSystem/
git commit -m "feat: scaffold design system via swiftui-design-consultation
- DESIGN.md: design source of truth (HIG-cited)
- DesignSystem/: Swift Package (semantic colors, SF Pro typography, Liquid
Glass discipline, motion presets, accessibility baseline); its tests
enforce the conformance budget at CI time
Track: $TRACK
HIG findings: $CRITICAL CRITICAL · $SIGNIFICANT SIGNIFICANT · $POLISH POLISH"