ds-extract-component
DS Extract Component — extracts an inline UI pattern from Swift code into a reusable component + creates matching Figma DS component. Full pipeline: identify pattern → extract Swift struct → add to pb
SKILL.md.claude/skills/ds-extract-component/SKILL.md
GitHubDS Extract Component
You extract inline UI patterns from Hexbound Swift code into proper reusable components and create matching Figma DS component sets.
Prerequisites
- Read
CLAUDE.md(root) — especially Xcode Project File section and Figma DS rules - Read
Hexbound/CLAUDE.md— iOS-specific rules - Read the Theme files to know available tokens:
DarkFantasyTheme.swift— colors, fontsLayoutConstants.swift— spacing, radius, iconsButtonStyles.swift— button stylesCardStyles.swift— card modifiersOrnamentalStyles.swift— ornamental overlays
Step 1: Identify the Pattern
Before extracting, answer these questions:
- Where does this pattern appear? List all files + line numbers
- What varies between instances? (text, color, icon, size, action)
- What stays constant? (layout, spacing, font, background shape)
- Is there an existing component it could extend? Check
Views/Components/first - What should it be called? Follow naming convention:
{Thing}{Role}View.swiftor{Thing}{Role}.swift
Step 2: Design the Component API
Design the Swift struct interface:
// Template:
struct ComponentName: View {
// Required parameters (what varies)
let title: String
let color: Color
// Optional parameters (with defaults)
var size: Size = .standard
var onTap: (() -> Void)? = nil
// Enum for variants (if applicable)
enum Size { case compact, standard, large }
var body: some View {
// ALL values from design system tokens:
// - Colors: DarkFantasyTheme.xxx
// - Fonts: DarkFantasyTheme.xxx
// - Spacing: LayoutConstants.xxx
// - Radius: LayoutConstants.xxx
// - Buttons: .buttonStyle(.xxx)
}
}
Rules for the component:
- ZERO hardcoded values — every color, font, spacing, radius from tokens
- Minimum font 11px (badge) or 12px (caption) — never smaller
- If it has a tap action → wrap in
Buttonwith.buttonStyle(.plain)or appropriate style - If it shows rarity → accept
ItemRarityparameter, useDarkFantasyTheme.rarityColor(for:) - If it shows class → accept
CharacterClassparameter, use class color tokens - If ornamental → use
.panelCard()/.rarityCard()/ appropriate card modifier
Step 3: Create the Swift File
Write the component to
Hexbound/Hexbound/Views/Components/ComponentName.swiftAdd to pbxproj — generate random 24-char hex IDs (NOT sequential):
openssl rand -hex 12 | tr 'a-f' 'A-F' # For fileRef ID openssl rand -hex 12 | tr 'a-f' 'A-F' # For buildFile IDAdd entries to ALL 4 sections: PBXBuildFile, PBXFileReference, PBXGroup (Components), PBXSourcesBuildPhase
Verify pbxproj — no duplicate IDs, entries sorted alphabetically
Step 4: Replace All Call Sites
For every instance of the inline pattern:
rg -nto find ALL occurrences- Replace each with the new component
- Verify the parameters match the original inline code
- Run CDO scan to confirm no violations introduced
CRITICAL: After refactoring, search ALL callers with rg to make sure nothing broke. Common mistakes:
- Missing import
- Parameter name mismatch
- Optional vs required parameter
- Closure signature change
Step 5: Create Figma DS Component
Use figma-use skill with the current verified DS file key. Historical default: uDjXIz7CdJxcEOI5jCBcjY; verify before writing.
Determine the correct Figma page:
| Component type | Figma page |
|---|---|
| Button variant | Components / Buttons |
| Card/panel | Components / Cards |
| Badge/pill/tag | Components / Badges & Pills |
| Progress indicator | Components / Progress Bars |
| Loading state | Components / Loading |
| Navigation element | Components / Navigation |
| Input field | Components / Input |
| Skeleton/placeholder | Components / Skeleton |
| Hero/character display | Components / Hero & Character |
| PvP/arena element | Components / Arena & PvP |
| Dungeon/quest element | Components / Dungeon & Progression |
| Social/messaging | Components / Social & Messaging |
| Toast/banner/alert | Components / Toast & Banners |
| Modal/sheet/overlay | Components / Modals & Sheets |
| Currency display | Components / Currency Display |
Build the Figma component:
- Create component variants matching Swift's enum/parameter variations
- Bind ALL colors to Color collection variables
- Bind ALL spacing to Spacing collection variables
- Apply text styles to ALL text nodes
- Apply effect styles to root node (Shadow/Card or Shadow/Modal)
- Use existing sub-components (Button instances, Divider instances, etc.)
Figma quality checklist (MANDATORY):
- Every TEXT node has
textStyleIdset (linked to Heading/* or Body/*) - Every colored fill/stroke has
boundVariables.fillsorboundVariables.strokes - Every auto-layout gap has
boundVariables.itemSpacing - Every padding has
boundVariables.paddingTop/Right/Bottom/Left - Every cornerRadius has
boundVariables.topLeftRadius(etc.) - Root component has effect style applied
- No FRAME nodes pretending to be buttons — use Button instances
- No RECTANGLE nodes pretending to be dividers — use Divider instances
- Component set uses
combineAsVariantswith clear property names
Step 6: Update Documentation
- Update
CLAUDE.md— if component count changed, update the Figma DS stats line - Update Figma page table in CLAUDE.md if new component added to existing page
- Update
docs/07_ui_ux/SCREEN_INVENTORY.mdif new component affects screen inventory
Step 7: Verify
Run full CDO scan:
# Token violations
rg -n 'DarkFantasyTheme\.(largeTitleFont|titleFont|bodyFont)' Hexbound -g '*.swift'
rg -n 'LayoutConstants\.(spacing|padding|margin)[A-Z]' Hexbound -g '*.swift'
# Component actually used
rg -n 'ComponentName' Hexbound/Hexbound/Views -g '*.swift' | wc -l
# pbxproj valid
rg 'ComponentName' Hexbound/Hexbound.xcodeproj/project.pbxproj | wc -l # Should be 4
Take a Figma screenshot of the new component to visually verify.
Example: Extracting "Class Tag" Pattern
Before (inline, repeated 3 times):
Text(opponent.characterClass.displayName.uppercased())
.font(DarkFantasyTheme.caption.bold())
.foregroundStyle(classColor)
.padding(.horizontal, LayoutConstants.spaceSM)
.padding(.vertical, LayoutConstants.space2XS)
.background(
RoundedRectangle(cornerRadius: LayoutConstants.radiusXS)
.fill(classColor.opacity(0.12))
.overlay(
RoundedRectangle(cornerRadius: LayoutConstants.radiusXS)
.stroke(classColor.opacity(0.25), lineWidth: 0.5)
)
)
After (extracted component):
struct ClassTagView: View {
let characterClass: CharacterClass
var body: some View {
let color = DarkFantasyTheme.classColor(for: characterClass)
Text(characterClass.displayName.uppercased())
.font(DarkFantasyTheme.caption.bold())
.foregroundStyle(color)
.padding(.horizontal, LayoutConstants.spaceSM)
.padding(.vertical, LayoutConstants.space2XS)
.background(
RoundedRectangle(cornerRadius: LayoutConstants.radiusXS)
.fill(color.opacity(0.12))
.overlay(
RoundedRectangle(cornerRadius: LayoutConstants.radiusXS)
.stroke(color.opacity(0.25), lineWidth: 0.5)
)
)
}
}
Call sites become: ClassTagView(characterClass: opponent.characterClass)
Figma: Component Set "Class Tag" on Badges & Pills page, 4 variants (Warrior/Rogue/Mage/Tank), all fills bound to class/* color variables.