@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/figma-common/figma-commit/COMMON_REBASE.md

@@ -0,0 +1,206 @@
+# Common Submodule — Rebase, Resolve, Validate & Push
+
+Handles `{project.slug}-common` branch creation, conflict resolution, regeneration, validation, and PR flow.
+
+Called from `/figma-commit` SKILL.md after code review passes.
+
+---
+
+## Inputs (from parent skill)
+
+| Variable | Source |
+|----------|--------|
+| `REPO_ROOT` | git repo root |
+| `COMMON_PATH` | `${REPO_ROOT}/{repos.common.path}` |
+| `BRANCH_NAME` | `feature/${JIRA_ISSUE}-${COMPONENT_KEBAB}-implementation` |
+| `JIRA_ISSUE` | Jira ticket |
+| `COMPONENT_PASCAL` | Component name |
+
+---
+
+## STEP 1 — Stash
+
+```bash
+cd "${COMMON_PATH}"
+git stash push -u -m "figma-commit: ${COMPONENT_PASCAL} pre-branch stash"
+```
+
+Skip if `git status --porcelain` is empty.
+
+## STEP 2 — Fetch & Branch from develop
+
+```bash
+cd "${COMMON_PATH}"
+git fetch origin develop
+git checkout develop
+git pull origin develop
+git checkout -b "${BRANCH_NAME}"
+```
+
+If branch already exists → append `-v2`, `-v3`, etc.
+
+## STEP 3 — Pop Stash
+
+```bash
+cd "${COMMON_PATH}"
+git stash pop
+```
+
+If pop succeeds cleanly → skip to STEP 5.
+If pop fails with conflicts → proceed to STEP 4.
+
+## STEP 4 — Conflict Resolution
+
+### 4A — Classify conflicted files
+
+| File Pattern | Strategy |
+|-------------|----------|
+| `iOS/Sources/*/Generated/*` | Accept either side (will regenerate) |
+| `Shared/Figma/Generated/*` | Accept either side (gitignored, will regenerate) |
+| `iOS/Sources/LocalizationAssets/Resources/*.xcstrings` | Accept either side (will regenerate) |
+| `iOS/Sources/AccessibilityAssets/Resources/*.xcstrings` | Accept either side (will regenerate) |
+| `Shared/Localization/*/Metadata/*` | Accept either side (gitignored, will regenerate) |
+| `Shared/UITestingIdentifiers/Metadata/*` | Accept either side (gitignored, will regenerate) |
+| `Sources/Suggested/*.json` | Our version wins (per-key files, we created them) |
+| Source JSONs (see below) | **Union merge** |
+| `Shared/Figma/Components/*.json` | Our version wins (we created/modified it) |
+
+### 4B — Union merge for source JSONs
+
+For each conflicted source JSON:
+
+```
+a. Accept OURS (develop) version: git checkout --ours <file> && git add <file>
+b. Manually insert only the NEW keys from the branch (use Edit tool, match existing format exactly)
+c. NEVER use Python json.dump or any JSON serializer — it reformats the entire file
+d. After manual edits, normalize with the Swift tool:
+   .build/debug/UITestingIdentifierTool format
+e. Verify: key count >= develop's count — no key lost
+```
+
+**Source files requiring union merge:**
+
+| File | Resolution | Format Tool |
+|------|-----------|-------------|
+| `Shared/UITestingIdentifiers/ui-testing-identifiers.json` | Accept ours + insert new keys | `UITestingIdentifierTool format` |
+| `Shared/UIAssets/Colors/*.json` | Accept ours + insert new entries | (manual — match existing format) |
+
+**Files that NO LONGER need union merge** (per-key files or gitignored):
+- `*-data-suggested.json` → replaced by `Sources/Suggested/*.json` (per-key files, never conflict)
+- `*-data-merged.json` → gitignored (derived artifact, regenerated in §5)
+- `*-metadata.json` → gitignored (derived artifact, regenerated in §5)
+- `Metadata/identifier-keys.json` → gitignored (derived artifact, regenerated in §5)
+
+### 4C — Text file union merge
+
+**No longer needed.** `localization-keys.txt` and `accessibility-keys.txt` are gitignored (regenerated in §5).
+
+### 4D — Verify no conflict markers remain
+
+```bash
+grep -r "<<<<<<" . --include="*.json" --include="*.swift" --include="*.txt" | head -5
+```
+
+## STEP 5 — Rebuild Derived Artifacts
+
+All derived artifacts (merged data, metadata, keys.txt, registries, catalogs) are gitignored. Always rebuild them after conflict resolution to guarantee fresh data.
+
+```bash
+bash "${REPO_ROOT}/.instructions/common/scripts/common-rebuild-derived-artifacts.sh"
+```
+
+This script rebuilds everything: merge translations from per-key `Sources/Suggested/` files, regenerate metadata, keys indexes, UI assets, token registries, and Figma catalogs.
+
+If the script fails → source JSON likely has invalid syntax from merge. Fix and retry.
+
+## STEP 6 — Validate Integrity
+
+Always fetch develop first so the non-destruction check compares against the latest:
+
+```bash
+cd "${COMMON_PATH}"
+git fetch origin develop
+
+python3 "${REPO_ROOT}/.instructions/figma/figma-commit/validate-localization-sync.py" \
+    --common-path "${COMMON_PATH}"
+```
+
+**Must exit 0.** Validates:
+1. Suggested covers merged — every merged key has a corresponding per-key file in `Sources/Suggested/`
+2. All 8 languages present per key — no missing translations
+3. No empty suggested values
+4. keys.txt and metadata in sync with merged
+5. Key count non-decreasing vs develop
+6. Non-destruction — no key removed vs develop
+7. Testing identifiers JSON ↔ keys JSON match
+
+If validation fails → fix before committing. Common fixes:
+- **Keys in merged not in suggested**: Add missing per-key file via `TranslationManagerTool add`
+- **Key count decreased**: Key lost during merge — find and restore the per-key file
+- **Empty values**: Translation added without content — provide it
+- **Non-destruction violation**: Intentional rename → re-add old key as alias
+
+## STEP 7 — Commit
+
+```bash
+cd "${COMMON_PATH}"
+git add -A
+git commit -m "$(cat <<'EOF'
+feat(common): [${JIRA_ISSUE}] add ${COMPONENT_PASCAL} tokens and keys
+
+- Add testing identifiers, localization, and accessibility keys
+- Add design tokens and component registry entry
+- Regenerate all platform code and catalogs
+
+Refs: ${JIRA_ISSUE}
+EOF
+)"
+```
+
+## STEP 8 — Push
+
+```bash
+cd "${COMMON_PATH}"
+git push -u origin "${BRANCH_NAME}"
+```
+
+## STEP 9 — Create PR (do NOT merge)
+
+```bash
+cd "${COMMON_PATH}"
+gh pr create --base develop \
+    --title "feat(common): [${JIRA_ISSUE}] add ${COMPONENT_PASCAL} tokens" \
+    --body "$(cat <<'EOF'
+## Summary
+- Add testing identifiers, localization, and accessibility keys
+- Add design tokens and component registry entry
+- Regenerate all platform code and catalogs
+
+## Visual Reference
+- **Figma:** ${FIGMA_URL}
+- **Confluence iOS:** ${CONFLUENCE_IOS_URL}
+
+## Validation
+- [ ] validate-localization-sync.py passes
+- [ ] No key count decrease vs develop
+- [ ] All 8 languages present
+
+Refs: ${JIRA_ISSUE}
+EOF
+)"
+```
+
+**Do NOT merge** — PR is created for review. Merging is a separate manual action.
+
+---
+
+## Error Handling
+
+- **Stash conflict on pop**: Follow §4 conflict resolution
+- **Branch already exists**: Append `-v2`, `-v3`
+- **Push rejected**: Report error, do NOT force-push
+- **Not on develop**: Warn user, ask confirmation
+- **Rebuild script fails**: Source JSON likely invalid from merge — fix and retry
+- **Validation fails**: Fix before committing — NEVER skip validation
+- **Key count decreased**: STOP — per-key file was lost, check `Sources/Suggested/` for missing files
+- **Same-key conflict in union merge**: Ask user which version to keep — do NOT silently overwrite (only applies to UIAssets Colors and UITestingIdentifiers now)

package/pipeline/skills/figma-common/figma-commit/REVIEW.md

@@ -0,0 +1,337 @@
+# Figma Component Code Review
+
+Pre-commit review checklist for components implemented via the `/figma` workflow.
+Run this review after all phases complete, before committing.
+
+**Input:** Component name and source location from `IMPLEMENTATION_HISTORY.md`.
+
+---
+
+## How To Use
+
+```
+Review the {ComponentName} component at {componentLocation} using the checklist in .instructions/figma/figma-commit/REVIEW.md
+```
+
+---
+
+## 1. File Completeness
+
+Verify all expected files exist at `{componentLocation}/`:
+
+| File | Required | Condition |
+|------|----------|-----------|
+| `{ComponentName}.swift` | Always | Main View |
+| `{ComponentName}Configuration.swift` | COMPLEX only | Configuration struct |
+| `{ComponentName}+Modifiers.swift` | COMPLEX only | View-level chain modifiers |
+| `{ComponentName}.figma.swift` | Always | Code Connect |
+| `FIGMA.md` | Always | Component documentation |
+
+Verify test files exist:
+
+| File | Required | Location |
+|------|----------|----------|
+| `{ComponentName}ViewInspectorTests.swift` | Always | `Tests/UIComponentsTests/ViewInspector/Components/.../` |
+| `{ComponentName}SnapshotTests.swift` | Always | `Tests/UIComponentsTests/Snapshot/Components/.../` |
+| Snapshot reference images | Never committed | `__Snapshots__/` is gitignored — generated on-demand via `record: .missing` |
+
+**FAIL if:** ViewInspector or Snapshot test file is missing. **FAIL if:** `__Snapshots__/` directory is tracked by git (should be gitignored).
+
+---
+
+## 2. No Magic Numbers
+
+Scan ALL production Swift files (NOT test files) for hardcoded values.
+
+### 2.1 Dimensions — Must Use Tokens or Named Constants
+
+Every numeric `CGFloat` in production code must come from a design token OR a named constant in a `private enum Constants`. Component-specific sizes that don't map to an existing design token (e.g., icon sizes from Figma specs) are valid in `Constants`:
+
+| Bad (magic number) | Good (token) |
+|--------------------|--------------|
+| `frame(height: 56)` | `frame(minHeight: .Size.size56)` |
+| `padding(20)` | `padding(.horizontal, .Spacing.spacing20)` |
+| `cornerRadius(8)` | `cornerRadius: .Radius.radius8` |
+| `lineWidth: 1` | `lineWidth: .BorderWidth.borderWidth1` |
+| `spacing: 4` | `spacing: .Spacing.spacing4` |
+| `width: 24, height: 24` | `width: .Size.size24, height: .Size.size24` |
+
+**How to check:**
+```
+Grep for raw numeric CGFloat values in {ComponentName}.swift and {ComponentName}+Modifiers.swift:
+- Pattern: \b\d+\.?\d*\b in frame/padding/spacing/cornerRadius/lineWidth/width/height contexts
+- Exclude: 0, 1 (only if used as multiplier/boolean, NOT as dimension)
+- Exclude: .infinity (SwiftUI constant)
+- Exclude: Values referenced via Constants.propertyName (named constants are NOT magic numbers)
+```
+
+**FAIL if:** Any raw inline dimension value found (e.g., `frame(height: 56)`). Named constants in `Constants` enum are PASS.
+
+### 2.2 Colors — Must Use Semantic Tokens
+
+Prefer design tokens. No `Color(red:green:blue:)`, no `UIColor` literals, no SwiftUI named colors (`.red`, `.white`).
+
+| Bad | Good |
+|-----|------|
+| `Color(red: 0.9, green: 0, blue: 0)` | `Color.Primary.primary` |
+| `Color.red` | `Color.Primary.primary` |
+| `Color.white` | `Color.Text.textWhite` or `Color.Button.buttonPrimaryWhite` |
+| `Color.clear` | `Color.clear` is ALLOWED (SwiftUI built-in, not a design token gap) |
+
+When a color has no matching design token and must be hardcoded in `Constants`, use the `Color(hex:)` initializer from UIExtensions (NOT `Color(red:green:blue:)`):
+
+| Bad (raw RGB) | Good (hex constant) |
+|---------------|---------------------|
+| `Color(red: 0.9, green: 0, blue: 0)` | `Color(hex: "#E50914")` |
+| `Color(.sRGB, red: 0.15, green: 0.68, blue: 0.38)` | `Color(hex: "#25AD61")` |
+
+**FAIL if:** `Color(red:green:blue:)`, `Color(.sRGB, ...)`, or SwiftUI named colors (`.red`, `.blue`, `.white`, etc.) found in production code.
+
+### 2.3 Typography — Must Use TypographyStyle
+
+No raw `.font()` calls. All text styling via `.typographyStyle()`.
+
+| Bad | Good |
+|-----|------|
+| `.font(.system(size: 18, weight: .bold))` | `.typographyStyle(.h6)` |
+| `.font(.headline)` | `.typographyStyle(.bodyBold)` |
+
+**FAIL if:** Any `.font()` call found in production code.
+
+### 2.4 Allowed Exceptions
+
+These raw values are acceptable and should NOT be flagged:
+
+- `0` as zero padding/offset
+- `.infinity` in `frame(maxWidth: .infinity)`
+- Named constants in `private enum Constants` — these are NOT magic numbers
+- Numeric values in test files (snapshot frame sizes, assertion values)
+- Numeric values in `#Preview` section labels (e.g., section divider count)
+- Opacity values (`0.0` to `1.0`) — no token system for opacity
+- `lineLimit(1)` — SwiftUI view modifier, not a dimension
+
+---
+
+## 3. Configuration Purity (COMPLEX only)
+
+Read `{ComponentName}Configuration.swift` and verify:
+
+| Rule | Check |
+|------|-------|
+| No closures | No `() -> Void`, `(T) -> Void`, `@escaping` in Configuration properties |
+| No bindings | No `Binding<T>`, `@Binding` in Configuration properties |
+| No state | No `@State`, `@ObservedObject`, `@StateObject`, `@EnvironmentObject` |
+| No view builders | No `AnyView`, `@ViewBuilder`, `some View` as properties |
+| Value types only | All properties should be `let` with value/enum/optional types |
+| `@GenerateChainModifiers` | Macro is applied to the struct |
+| `Sendable` conformance | Struct conforms to `Sendable` |
+
+**FAIL if:** Any non-value-type property found in Configuration.
+
+---
+
+## 4. +Modifiers Correctness (COMPLEX only)
+
+Read `{ComponentName}+Modifiers.swift` and verify:
+
+| Rule | Check |
+|------|-------|
+| One method per Configuration property | Count matches (excluding `@IgnoreChainModifier` properties) |
+| Localized overloads for String props | `func title(localized value: LocalizationStringKey)` exists for each String property |
+| Delegates to `configured { }` | Every method body is `configured { $0.propertyName(value) }` |
+| Return type is concrete | Returns `{ComponentName}`, not `Self` or `some View` |
+| Correct nested type paths | Enum parameters use `{ComponentName}Configuration.EnumType` |
+| `import CoreLocalization` | Present if any localized overload exists |
+
+**FAIL if:** Method count mismatch or incorrect delegation pattern.
+
+---
+
+## 5. Accessibility
+
+Read `{ComponentName}.swift` and verify:
+
+| Rule | Check |
+|------|-------|
+| Interactive elements have identifiers | `.accessibilityIdentifier(.{ComponentName}.elementName)` on buttons, taps |
+| Uses type-safe keys | `.accessibilityIdentifier(.ComponentName.key)` NOT `.accessibilityIdentifier("raw_string")` |
+| Container combining | `.accessibilityElement(children: .combine)` on composite interactive elements |
+| Icons are decorative | `.accessibilityHidden(true)` on decorative icons within labeled buttons |
+| No redundant labels | Don't add `.accessibilityLabel` if SwiftUI `Button` + `Text` already provides it |
+
+**FAIL if:** Interactive elements lack identifiers, or raw strings used instead of type-safe keys.
+
+---
+
+## 6. Analytics
+
+Read `{ComponentName}.swift` and verify:
+
+| Rule | Check |
+|------|-------|
+| Tappable elements tracked | `.analyticsButton(id:label:type:)` on buttons |
+| ID uses testing identifier | `id: UITestingIdentifierKey.{ComponentName}.element.identifier` |
+| Type mapping correct | Style/variant maps to correct `ButtonType` (primary/secondary/ghost/tertiary) |
+| No duplicate tracking | One analytics modifier per user action, not per sub-view |
+
+**WARN if:** Missing analytics on tappable elements. Not always a hard fail (some components are purely presentational).
+
+---
+
+## 7. Testing Identifiers
+
+Verify the identifier pipeline is complete:
+
+| Step | Check |
+|------|-------|
+| Registered | `UITestingIdentifierTool check --key '{ComponentName}.element'` returns `✅ Key exists` for all identifiers |
+| Generated keys | `UITestingIdentifierKeys.swift` has `enum {ComponentName}` with static keys |
+| View usage | `{ComponentName}.swift` uses `.accessibilityIdentifier(.{ComponentName}.key)` |
+| Test assertions | ViewInspector tests assert identifier presence |
+
+**FAIL if:** Any step in the pipeline is missing or inconsistent.
+
+---
+
+## 8. Preview Quality
+
+Read the Preview section at the bottom of `{ComponentName}.swift`:
+
+| Rule | Check |
+|------|-------|
+| LTR preview exists | `{ComponentName}Preview: View` struct + `#Preview` |
+| RTL preview exists | `{ComponentName}RTLPreview: View` struct + `#Preview("RTL")` |
+| +Modifiers style | Uses `{ComponentName} { }.prop(val)` NOT `{ config in config.prop(val) }` |
+| All variants shown | Every enum `allCases` iterated via `ForEach` |
+| RTL has Arabic text | Localized text props use Arabic placeholders |
+| RTL environment set | `.environment(\.layoutDirection, .rightToLeft)` + `.environment(\.locale, Locale(identifier: "ar"))` |
+| Preview structs are plain | No macros on preview structs (workaround for `#Preview` + macro conflict) |
+| Disabled state shown | If component supports disabled, shown with `.disabled(true)` |
+
+**FAIL if:** Missing LTR or RTL preview, or using old configure-closure style.
+
+---
+
+## 9. Code Connect
+
+Read `{ComponentName}.figma.swift`:
+
+| Rule | Check |
+|------|-------|
+| `import Figma` | Present |
+| Correct `figmaNodeUrl` | Contains correct fileKey and nodeId |
+| +Modifiers style | Body uses `.prop(val)` chain, NOT `{ config in ... }` |
+| All variant groups covered | Separate `FigmaConnect` struct per variant group |
+| `@FigmaEnum` uses shorthand | `.enumCase` NOT `Type.enumCase` |
+| `#Preview` at bottom | At least one preview for compile validation |
+
+**FAIL if:** Wrong node URL, missing variant coverage, or old closure style.
+
+---
+
+## 10. View Implementation Quality
+
+Read `{ComponentName}.swift` (the View, excluding Preview section):
+
+| Rule | Check |
+|------|-------|
+| `@GenerateConfiguredInit` | Applied to the View struct |
+| `public struct` | View is public |
+| `public let configuration` | Configuration property is public let |
+| `@Environment(\.isEnabled)` | Used for disabled state (NOT a config boolean) |
+| No force unwraps | No `!` on optionals in production code |
+| No `print`/`debugPrint` | No debug logging in production code |
+| Correct MARK sections | `// MARK: - Properties`, `// MARK: - Body`, `// MARK: - Subviews`, `// MARK: - Computed Properties` |
+| `@ViewBuilder` on conditional views | Optional subviews use `@ViewBuilder` |
+| No unused imports | Every `import` is actually used |
+
+**FAIL if:** Missing macro annotation, force unwraps, or debug logging.
+
+---
+
+## 11. FIGMA.md Documentation
+
+Read `{componentLocation}/FIGMA.md`:
+
+| Rule | Check |
+|------|-------|
+| Figma link present | Contains `https://www.figma.com/design/{fileKey}/?node-id={nodeId}` |
+| Variant mapping table | Maps Figma property values to Swift enum cases |
+| Usage example | Shows basic instantiation |
+| Code Connect section | Lists strategy and property mappings |
+
+**FAIL if:** Missing Figma link or variant mapping table.
+
+---
+
+## 12. Build Verification
+
+```bash
+xcodebuild build -project {build.xcodeproj} -scheme {build.scheme} \
+    -destination 'generic/platform=iOS' CODE_SIGNING_ALLOWED=NO -quiet
+```
+
+**FAIL if:** Build errors. Warnings on component files should be investigated.
+
+---
+
+## 13. Test Verification
+
+```bash
+REPO_ROOT=$(git rev-parse --show-toplevel)
+bash "${REPO_ROOT}/.instructions/figma/figma-to-swiftui/scripts/run-uicomponents-tests.sh" --filter "{ComponentName}ViewInspectorTests"
+bash "${REPO_ROOT}/.instructions/figma/figma-to-swiftui/scripts/run-uicomponents-tests.sh" --filter "{ComponentName}SnapshotTests"
+```
+
+**FAIL if:** Any test fails or test count is zero.
+
+---
+
+## Review Output Format
+
+```
+## Code Review: {ComponentName}
+
+### Status: PASS / FAIL / WARN
+
+### Checklist
+
+| # | Check | Status | Notes |
+|---|-------|--------|-------|
+| 1 | File completeness | PASS/FAIL | {missing files if any} |
+| 2 | No magic numbers | PASS/FAIL | {violations if any} |
+| 3 | Configuration purity | PASS/FAIL/N/A | {violations if any} |
+| 4 | +Modifiers correctness | PASS/FAIL/N/A | {violations if any} |
+| 5 | Accessibility | PASS/FAIL | {missing identifiers if any} |
+| 6 | Analytics | PASS/WARN | {missing tracking if any} |
+| 7 | Testing identifiers | PASS/FAIL | {pipeline gaps if any} |
+| 8 | Preview quality | PASS/FAIL | {issues if any} |
+| 9 | Code Connect | PASS/FAIL | {issues if any} |
+| 10 | View implementation | PASS/FAIL | {issues if any} |
+| 11 | FIGMA.md docs | PASS/FAIL | {issues if any} |
+| 12 | Build | PASS/FAIL | {errors if any} |
+| 13 | Tests | PASS/FAIL | {failures if any} |
+
+### Violations (if any)
+
+{Detailed list of each violation with file:line, what's wrong, and suggested fix}
+
+### Summary
+
+{One paragraph: overall assessment, blocking issues, suggestions}
+```
+
+---
+
+## Severity Levels
+
+| Level | Meaning | Action |
+|-------|---------|--------|
+| **FAIL** | Blocking — must fix before commit | Fix all FAIL items |
+| **WARN** | Non-blocking — should fix but can commit | Document in PR description |
+| **PASS** | Compliant | No action needed |
+| **N/A** | Not applicable | SIMPLE components skip Configuration/+Modifiers checks |
+
+**Overall status:**
+- Any FAIL → overall FAIL (do not commit)
+- All PASS/WARN/N/A → overall PASS (safe to commit)