@3fn/core 13.0.0

package/application-mcp-server/src/watcher/FileWatcher.ts

@@ -0,0 +1,104 @@
+/**
+ * Application MCP File Watcher
+ *
+ * Monitors all data source directories for changes and triggers
+ * appropriate reindex on the ComponentIndexer.
+ *
+ * Data sources:
+ * - components: schema.yaml, contracts.yaml, component-meta.yaml → reindexComponent
+ * - patterns: *.yaml → reindexPatterns
+ * - templates: *.yaml → reindexTemplates
+ * - guidance: *.yaml → reindexGuidance
+ * - token-index: *.yaml → reindexTokens
+ *
+ * @see Spec 106 R4 — expanded watching
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { ComponentIndexer } from '../indexer/ComponentIndexer';
+
+const COMPONENT_FILES = new Set(['contracts.yaml', 'component-meta.yaml']);
+
+interface WatchConfig {
+  dir: string;
+  handler: (filename: string) => void;
+}
+
+export class FileWatcher {
+  private watchers: fs.FSWatcher[] = [];
+  private debounceTimers = new Map<string, NodeJS.Timeout>();
+
+  constructor(
+    private indexer: ComponentIndexer,
+    private componentsDir: string,
+    private patternsDir?: string,
+    private templatesDir?: string,
+    private guidanceDir?: string,
+    private tokenIndexDir?: string,
+    private debounceMs: number = 100,
+  ) {}
+
+  start(): void {
+    this.stop();
+
+    const configs: WatchConfig[] = [
+      { dir: this.componentsDir, handler: (f) => this.handleComponentChange(f) },
+    ];
+
+    if (this.patternsDir) configs.push({ dir: this.patternsDir, handler: () => this.debounceReindex('patterns', () => this.indexer.reindexPatterns(this.patternsDir!)) });
+    if (this.templatesDir) configs.push({ dir: this.templatesDir, handler: () => this.debounceReindex('templates', () => this.indexer.reindexTemplates(this.templatesDir!)) });
+    if (this.guidanceDir) configs.push({ dir: this.guidanceDir, handler: () => this.debounceReindex('guidance', () => this.indexer.reindexGuidance(this.guidanceDir!)) });
+    if (this.tokenIndexDir) configs.push({ dir: this.tokenIndexDir, handler: () => this.debounceReindex('tokens', () => this.indexer.reindexTokens(this.tokenIndexDir!)) });
+
+    for (const config of configs) {
+      if (!fs.existsSync(config.dir)) continue;
+      try {
+        const watcher = fs.watch(config.dir, { recursive: true }, (_event, filename) => {
+          if (filename && filename.endsWith('.yaml')) config.handler(filename);
+        });
+        watcher.on('error', (err) => console.error(`FileWatcher error (${config.dir}): ${err.message}`));
+        this.watchers.push(watcher);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`FileWatcher: could not watch ${config.dir}: ${msg}`);
+      }
+    }
+  }
+
+  stop(): void {
+    for (const w of this.watchers) w.close();
+    this.watchers = [];
+    for (const timer of this.debounceTimers.values()) clearTimeout(timer);
+    this.debounceTimers.clear();
+  }
+
+  isWatching(): boolean {
+    return this.watchers.length > 0;
+  }
+
+  private handleComponentChange(filename: string): void {
+    const base = path.basename(filename);
+    if (!base.endsWith('.schema.yaml') && !COMPONENT_FILES.has(base)) return;
+
+    const componentDir = path.join(this.componentsDir, path.dirname(filename));
+    this.debounceReindex(componentDir, () => this.indexer.reindexComponent(componentDir));
+  }
+
+  private debounceReindex(key: string, action: () => Promise<void>): void {
+    const existing = this.debounceTimers.get(key);
+    if (existing) clearTimeout(existing);
+
+    const timer = setTimeout(async () => {
+      this.debounceTimers.delete(key);
+      try {
+        await action();
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`FileWatcher reindex failed (${key}): ${msg}`);
+      }
+    }, this.debounceMs);
+
+    this.debounceTimers.set(key, timer);
+  }
+}

package/application-mcp-server/src/watcher/__tests__/FileWatcher.test.ts

@@ -0,0 +1,59 @@
+/**
+ * FileWatcher Integration Tests
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { ComponentIndexer } from '../../indexer/ComponentIndexer';
+import { FileWatcher } from '../FileWatcher';
+
+const COMPONENTS_DIR = path.resolve(__dirname, '../../../../src/components/core');
+
+describe('FileWatcher', () => {
+  let indexer: ComponentIndexer;
+  let watcher: FileWatcher;
+
+  beforeAll(async () => {
+    indexer = new ComponentIndexer();
+    await indexer.indexComponents(COMPONENTS_DIR);
+  });
+
+  afterEach(() => {
+    watcher?.stop();
+  });
+
+  it('starts and stops without error', () => {
+    watcher = new FileWatcher(indexer, COMPONENTS_DIR, undefined, undefined, undefined, undefined, 50);
+    watcher.start();
+    expect(watcher.isWatching()).toBe(true);
+    watcher.stop();
+    expect(watcher.isWatching()).toBe(false);
+  });
+
+  it('does not throw on nonexistent directory', () => {
+    watcher = new FileWatcher(indexer, '/nonexistent/path');
+    // Missing directories are skipped gracefully (Spec 106 R4 AC3)
+    watcher.start();
+    expect(watcher.isWatching()).toBe(false);
+  });
+
+  it('re-indexes on file touch', async () => {
+    watcher = new FileWatcher(indexer, COMPONENTS_DIR, undefined, undefined, undefined, undefined, 50);
+    watcher.start();
+
+    const before = indexer.getComponent('Badge-Count-Base');
+    const beforeTime = before!.indexedAt;
+
+    // Touch the contracts.yaml to trigger a change event
+    const contractsPath = path.join(COMPONENTS_DIR, 'Badge-Count-Base', 'contracts.yaml');
+    const content = fs.readFileSync(contractsPath, 'utf-8');
+    fs.writeFileSync(contractsPath, content); // write same content = touch
+
+    // Wait for debounce + reindex
+    await new Promise(r => setTimeout(r, 300));
+
+    const after = indexer.getComponent('Badge-Count-Base');
+    expect(after).not.toBeNull();
+    expect(after!.indexedAt).not.toBe(beforeTime);
+  });
+});

package/application-mcp-server/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "moduleResolution": "node"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}

package/bin/designerpunk.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/**
+ * DesignerPunk CLI — bin entry point
+ *
+ * Invokes the COMPILED CLI's __main(). No process-global tsx register.
+ *
+ * Spec 118 Increment 3a — runtime unification (tsx is the SOLE runtime TS mechanism).
+ * The interpreter line stays `#!/usr/bin/env node` because `node` is the ONLY interpreter
+ * guaranteed on a consumer's PATH (tsx is an npm dependency, not a guaranteed global).
+ *
+ * THE FINAL COHERENT END-STATE (Spec 118 Task 9.5.3 + Spec 124):
+ * The global `tsx/cjs/api` register() is RETIRED. The bin invokes the compiled
+ * `dist/cli/designerpunk.js` directly under plain node — no process-global runtime-TS
+ * register exists. This is the destination the prior interim deliberately stopped short of.
+ *
+ *   The earlier interim kept a global register because it was load-bearing for MORE than
+ *   the CLI's own `.ts` source: the CLI also `require()`s the CONSUMER'S raw `.ts` at
+ *   generate-time — `resolveTokens` (`<consumer>/src/tokens`) and `loadComponentTokens`
+ *   (`<consumer>/.../component/*.ts`). Retiring the global register safely required the
+ *   audit + per-site seams to be in place first. They now are:
+ *
+ *     - Consumer raw-`.ts` loading is handled by the PER-SITE SCOPED-tsx SEAMS (Task 9.5.1):
+ *       `resolveTokens` / `loadComponentTokens` scope tsx at the call site (as Increment 1
+ *       did for loadConfig) instead of relying on a process-global register.
+ *     - The component-token seam is now a RETURN-VALUE / BRANDED-HARVEST seam (Spec 124):
+ *       `defineComponentTokens` brands its return value and no longer self-registers;
+ *       `loadComponentTokens` harvests the branded exports and is the sole writer to
+ *       `ComponentTokenRegistry`. This removed the dual-instance shared-singleton split
+ *       that a registerless bin previously exposed across the scoped-tsx boundary.
+ *
+ *   With the audit done (9.5 target model, ratified), the scoped-tsx seams in place
+ *   (9.5.1/9.5.2), and 124's return-value seam landed, no process-global register is needed.
+ *
+ * Why __main() instead of relying on module-level execution:
+ * Node 22 sets require.main to THIS file (bin/designerpunk.js), not the
+ * CLI module. A `require.main === module` guard in designerpunk.ts would
+ * prevent execution in consumer context (npx from node_modules).
+ * __main() bypasses this — the bin entry explicitly triggers the CLI.
+ *
+ * @see Spec 118 Task 9.5.3 (final bin-register retirement)
+ * @see Spec 124 (Component-Token Return Contract — the return-value seam)
+ * @see .kiro/issues/2026-06-10-cli-bundle-remove-wildcard-export.md
+ */
+
+require('../dist/cli/designerpunk.js').__main();

package/design-language/design-philosophy.yaml

@@ -0,0 +1,139 @@
+# DesignerPunk Design Philosophy
+# Source data for Application MCP's design language tools.
+# Indexed by DesignPhilosophyIndexer via DataPaths config.
+
+schemaVersion: 1
+
+philosophy:
+  northStar: "Electric Precision"
+  description: |
+    DesignerPunk's visual identity lives at the intersection of mathematical rigor and electric energy. The layout is calm; the color is not. Structure and hierarchy follow Wise-level clarity: generous whitespace, obvious information architecture, content-first composition. Color and accent follow Edgerunners-level commitment: vivid, saturated, unapologetic. These don't compete because they operate on different dimensions. Clarity for structure. Intensity for voice. Every value is traceable to a formula. Every color earns its place through contrast and intent.
+  characteristics:
+    - "Electric color commitment regardless of mode. Light surfaces are clean and bright with vivid accents that pop. Dark surfaces are deep with accents that glow."
+    - "Saturated accents with distinct semantic roles: cyan for action/navigation/selection, purple for tech/data, pink for error, yellow for attention, green for success, orange for warning and human identity, teal for information and agent identity"
+    - "Glow effects as a signature element for surface layering and depth (neon aesthetic, purposeful not decorative)"
+    - "Code as visual language. The <!-- logo references HTML's foundational syntax. Sparingly used code markers (//) are part of the brand experience. The machinery is visible."
+    - "8px baseline grid for layout, 4px sub-grid for typography. All elements cumulatively align to multiples of 8."
+    - "Three font families: Rajdhani (display/headings), Figtree (body/UI), Commit Mono (code/data/tokens)"
+    - "Semantic spacing categories encode design intent (grouped/related/separated/sectioned/inset)"
+    - "Concept-first color naming organized by role (feedback, identity, action, contrast, structure, progress), not by hue"
+    - "Blend utilities for state modifications (hover, pressed, disabled) rather than hardcoded state colors"
+    - "Unitless token architecture with build-time platform separation (CSS, Swift, Kotlin from single source)"
+    - "Dual themes: Original (maximum aesthetic impact) + WCAG 2.1 AA (accessible while maintaining character), each with light/dark modes"
+
+rules:
+  - name: "The Formula Rule"
+    constraint: "Every value must be derivable from a mathematical relationship"
+    rationale: "Traceability creates trust. Arbitrary values erode system integrity."
+  - name: "The Semantic-First Rule"
+    constraint: "Use semantic tokens before primitives. Only reach for primitives when no semantic token exists for the use case."
+    rationale: "Semantics encode intent; primitives encode value. Intent is more stable than value."
+  - name: "The Contract Rule"
+    constraint: "Every component behavior is explicit, documented, and testable across platforms"
+    rationale: "Implicit behavior creates platform drift. Explicit contracts prevent it."
+  - name: "The Clarity Rule"
+    constraint: "Layout and hierarchy must be immediately obvious. If you have to study it to understand it, simplify."
+    rationale: "Electric color earns its impact from calm structure. Chaos plus intensity is noise."
+  - name: "The Earn-Your-Glow Rule"
+    constraint: "Glow effects are used for layering surfaces and creating depth. Pair complementary colors for glow relationships."
+    rationale: "Neon glow communicates elevation and spatial relationships, not decoration. Complementary pairings create visual harmony within intensity."
+  - name: "The One-Accent Rule"
+    constraint: "No more than one accent hue per component or interaction moment. Pair complementary colors across adjacent surfaces, not within a single element."
+    rationale: "Each color has a semantic role. Mixing roles in one element creates confusion. Complementary pairing across surfaces creates cohesion."
+  - name: "The Visible Machinery Rule"
+    constraint: "Code syntax markers (//, <!--) are used sparingly as brand voice, not as decoration or on every surface"
+    rationale: "The system acknowledges its nature. But overuse turns a signature into a gimmick."
+  - name: "The Mode-Neutral Rule"
+    constraint: "Design for both light and dark modes. Neither is an afterthought. Both must feel intentionally DesignerPunk."
+    rationale: "The electric palette works in both modes. Light isn't safe mode. Dark isn't cool mode. Both are the brand."
+  - name: "The Break-Glass Rule"
+    constraint: "Rules can be broken for moments of critical impact, but only sparingly and with explicit authorization."
+    rationale: "A system that never breaks its own rules is rigid. A system that breaks them without discipline is chaos. The exception proves the rule when it's earned."
+
+guidance:
+  do:
+    - category: "spacing"
+      directive: "Use the 8px baseline grid for layout elements. Typography falls on a 4px sub-grid. All elements must cumulatively align to multiples of 8."
+    - category: "spacing"
+      directive: "Use semantic spacing tokens (space.grouped, space.separated, space.inset) to encode relationships"
+    - category: "spacing"
+      directive: "Vary spacing for rhythm; uniform padding is monotony"
+    - category: "spacing"
+      directive: "Use space075 (6) and space125 (10) when needed to maintain cumulative 8px alignment with typographic elements"
+    - category: "color"
+      directive: "Use saturated accents with their semantic roles: cyan for action/navigation, purple for tech/data, pink for error, yellow for attention, green for success, orange for warning, teal for info"
+    - category: "color"
+      directive: "Pair complementary colors across adjacent surfaces for cohesion"
+    - category: "color"
+      directive: "Design for both light and dark modes with equal intentionality"
+    - category: "typography"
+      directive: "Use Rajdhani for display/headings, Figtree for body/UI, Commit Mono for code/data/tokens"
+    - category: "typography"
+      directive: "Cap body text at 65-75ch"
+    - category: "typography"
+      directive: "Use weight contrast for hierarchy within a family (not font switching)"
+    - category: "motion"
+      directive: "Use expo-out easing on web/Android; spring physics on iOS"
+    - category: "motion"
+      directive: "Respect prefers-reduced-motion on all animations"
+    - category: "elevation"
+      directive: "Use glow effects for surface layering and depth with complementary color pairings"
+    - category: "elevation"
+      directive: "Tint shadows toward blue or gray (warm-light-cool-shadow principle)"
+    - category: "brand"
+      directive: "Use code syntax markers (//, <!--) sparingly as voice"
+    - category: "brand"
+      directive: "Let the system acknowledge its own nature; don't hide the machinery"
+    - category: "general"
+      directive: "Reference token names in specs, not pixel values"
+  dont:
+    - category: "spacing"
+      directive: "Use spacing values that break cumulative 8px alignment"
+    - category: "color"
+      directive: "Use more than one accent hue per component"
+    - category: "color"
+      directive: "Use glow effects decoratively (they communicate depth, not decoration)"
+    - category: "color"
+      directive: "Default to muted/safe palettes. The electric palette is the brand regardless of mode."
+    - category: "typography"
+      directive: "Use decorative or display typefaces outside of Rajdhani"
+    - category: "typography"
+      directive: "Use monospace for non-technical content"
+    - category: "motion"
+      directive: "Use bounce or elastic easing on web/Android"
+    - category: "motion"
+      directive: "Add motion that doesn't communicate state or spatial relationship"
+    - category: "elevation"
+      directive: "Use pure black shadows (always tint toward blue or gray)"
+    - category: "brand"
+      directive: "Overuse code syntax markers (sparingly = signature; everywhere = gimmick)"
+    - category: "general"
+      directive: "Hedge in copy ('you might want to consider' becomes 'use')"
+    - category: "general"
+      directive: "Use glassmorphism, gradient text, or side-stripe borders"
+    - category: "general"
+      directive: "Use identical card grids without hierarchy variation"
+    - category: "general"
+      directive: "Break rules without explicit authorization (see The Break-Glass Rule)"
+
+colorStrategy:
+  - tier: "Restrained"
+    definition: "Neutral surfaces dominate. One accent color at 10% or less of the surface. Semantic roles only (action buttons, links, state indicators)."
+    whenToUse: "Product register defaults. Settings pages, data tables, admin panels, dense information screens, long-form reading."
+    whenNotToUse: "Brand-heavy surfaces, hero sections, onboarding, celebration moments."
+    example: "A settings screen with white/gray surfaces and cyan only on the save button and active nav item."
+  - tier: "Committed"
+    definition: "One saturated color carries 30-60% of the surface. The color IS the statement."
+    whenToUse: "Hero sections, feature highlights, onboarding flows, marketing pages, brand-register surfaces."
+    whenNotToUse: "Dense data interfaces, multi-action screens, long-form reading."
+    example: "A hero section with a deep cyan background, white text, and a complementary purple glow on the primary CTA."
+  - tier: "Full Palette"
+    definition: "3-4 semantic color roles used deliberately across the surface. Each color earns its place through its assigned role."
+    whenToUse: "Dashboards, status overviews, multi-category interfaces, data visualization, progress flows."
+    whenNotToUse: "Simple forms, single-purpose screens, text-heavy content."
+    example: "A dashboard with cyan for active actions, green for success states, orange for warnings, and purple for data visualizations."
+  - tier: "Drenched"
+    definition: "The surface IS the color. Color is the dominant visual element. Content is secondary to atmosphere."
+    whenToUse: "Splash screens, loading states, celebration moments, brand campaigns, critical impact moments (Break-Glass Rule applies)."
+    whenNotToUse: "Any screen where the user needs to read, interact, or complete a task."
+    example: "An app launch screen entirely in electric cyan with the <!--DesignerPunk logo in white. Or a success celebration that floods the screen in green."

package/designerpunk.config.ts

@@ -0,0 +1,27 @@
+/**
+ * DesignerPunk Pipeline Configuration
+ *
+ * Default configuration for the DesignerPunk repo itself.
+ * Serves as both the working config and a reference example for product repos.
+ *
+ * Product repos create their own `designerpunk.config.ts` with:
+ * - Custom name and abbreviation for generated type names
+ * - Theme registrations with imported SemanticOverrides
+ * - Component token directories
+ * - Output directory
+ *
+ * @see docs/roadmap/integration-guide-draft.md
+ */
+
+import { defineConfig } from './src/config';
+
+export default defineConfig({
+  name: 'DesignerPunk',
+  abbreviation: 'DP',
+  themes: [],
+  componentTokens: [
+    './src/components/core',
+    './src/tokens/component',
+  ],
+  output: './dist',
+});

package/dist/ComponentTokens.android.kt

@@ -0,0 +1,105 @@
+/**
+ * DesignerPunk Design System - Component Tokens
+ * Generated: 2026-07-05T14:35:59.916Z
+ * Version: 1.0.0
+ * Platform: Android (Kotlin Constants)
+ *
+ * Component-specific tokens that reference primitive tokens.
+ * Use these for component-level styling consistency.
+ */
+
+package com.designerpunk.tokens
+
+/** Avatar Component Tokens */
+object AvatarTokens {
+    // Extra small avatar (24px). Compact contexts — inline mentions, dense lists.
+    val sizeXs = SizingTokens.size300
+    // Small avatar (32px). Comment threads, contact lists.
+    val sizeSm = SizingTokens.size400
+    // Medium avatar (40px). Default size — profile cards, list items.
+    val sizeMd = SizingTokens.size500
+    // Large avatar (48px). Profile headers, prominent identity display.
+    val sizeLg = SizingTokens.size600
+    // Extra large avatar (80px). Profile pages, hero sections.
+    val sizeXl = SizingTokens.size1000
+    // Extra extra large avatar (128px). Full profile view, onboarding.
+    val sizeXxl = SizingTokens.size1600
+    // Icon size for xs avatar (12px = 1.5× base) maintains 50% ratio (12/24). No existing icon token at this size, so component token fills the gap.
+    val iconSizeXs = 12.dp
+    // Icon size for xxl avatar (64px = 8× base) maintains 50% ratio (64/128). No existing icon token at this size, so component token fills the gap.
+    val iconSizeXxl = 64.dp
+}
+
+/** BadgeLabelBase Component Tokens */
+object BadgeLabelBaseTokens {
+    // Maximum width for truncated badges; allows ~12-15 characters before ellipsis while maintaining compact badge appearance. Value follows spacing family pattern (8 × 15 = 120px) but exceeds standard spacing scale, requiring component-level definition.
+    val maxWidth = 120.dp
+}
+
+/** ButtonIcon Component Tokens */
+object ButtonIconTokens {
+    // Large button variant requires 12px padding (1.5× base) for comfortable touch target and visual balance with larger icon sizes
+    val insetLarge = SpacingTokens.space150
+    // Medium button variant uses 10px padding (1.25× base strategic flexibility token) for compact appearance while maintaining adequate touch area
+    val insetMedium = SpacingTokens.space125
+    // Small button variant uses 8px padding (1× base) for minimal footprint in dense UI layouts while meeting minimum touch target requirements
+    val insetSmall = SpacingTokens.space100
+    // Large button size (48px = 6× base) provides generous touch target exceeding tapAreaRecommended, calculated as icon (24px) + padding (12px × 2)
+    val sizeLarge = SpacingTokens.size600
+    // Medium button size (40px = 5× base) provides standard touch target, calculated as icon (18px) + padding (10px × 2) rounded to grid
+    val sizeMedium = SpacingTokens.size500
+    // Small button size (32px = 4× base) provides compact visual footprint, calculated as icon (13px) + padding (8px × 2) rounded to grid
+    val sizeSmall = SpacingTokens.size400
+}
+
+/** InputCheckbox Component Tokens */
+object InputCheckboxTokens {
+    // Small checkbox box (24px). icon.size050 (16px) + inset.050 (4px) × 2.
+    val boxSm = SizingTokens.size300
+    // Medium checkbox box (32px). icon.size075 (20px) + inset.075 (6px) × 2.
+    val boxMd = SizingTokens.size400
+    // Large checkbox box (40px). icon.size100 (24px) + inset.100 (8px) × 2.
+    val boxLg = SizingTokens.size500
+}
+
+/** InputRadio Component Tokens */
+object InputRadioTokens {
+    // Small radio box (24px). Same dimensions as checkbox sm.
+    val boxSm = SizingTokens.size300
+    // Medium radio box (32px). Same dimensions as checkbox md.
+    val boxMd = SizingTokens.size400
+    // Large radio box (40px). Same dimensions as checkbox lg.
+    val boxLg = SizingTokens.size500
+}
+
+/** Progress Component Tokens */
+object ProgressTokens {
+    // Small node base size (12px). Inactive dots in compact mobile contexts.
+    val nodeSizeSm = SpacingTokens.size150
+    // Medium node base size (16px). Default inactive dot size.
+    val nodeSizeMd = SpacingTokens.size200
+    // Large node base size (20px). Inactive dots in desktop contexts.
+    val nodeSizeLg = SpacingTokens.size250
+    // Current node emphasis for sm (16px). +4px over base 12px for non-color visual differentiation.
+    val nodeSizeSmCurrent = SpacingTokens.size200
+    // Current node emphasis for md (20px). +4px over base 16px for non-color visual differentiation.
+    val nodeSizeMdCurrent = SpacingTokens.size250
+    // Current node emphasis for lg (24px). +4px over base 20px for non-color visual differentiation.
+    val nodeSizeLgCurrent = SpacingTokens.size300
+    // Small gap between nodes (6px = 0.75× base). Tight spacing for compact pagination dots in mobile contexts.
+    val nodeGapSm = SpacingTokens.space075
+    // Medium gap between nodes (8px = 1× base). Default spacing for stepper nodes, providing clear separation without excessive whitespace.
+    val nodeGapMd = SpacingTokens.space100
+    // Large gap between nodes (12px = 1.5× base). Generous spacing for detailed steppers with labels in desktop contexts.
+    val nodeGapLg = SpacingTokens.space150
+    // Connector line thickness (1px). References borderDefault primitive for consistent border treatment across the design system.
+    val connectorThickness = SpacingTokens.borderWidth100
+}
+
+/** VerticalListItem Component Tokens */
+object VerticalListItemTokens {
+    // Block padding at rest state (1px border). 11px padding + 1px border = 12px per side, achieving 48px total with 24px content. Uses TokenWithValue pattern as no primitive token exists for 11px.
+    val paddingBlockRest = 11.dp
+    // Block padding when selected (2px border). 10px padding + 2px border = 12px per side, maintaining 48px total with 24px content. References space125 strategic flexibility token.
+    val paddingBlockSelected = SpacingTokens.space125
+}

package/dist/ComponentTokens.ios.swift

@@ -0,0 +1,105 @@
+///
+/// DesignerPunk Design System - Component Tokens
+/// Generated: 2026-07-05T14:35:59.916Z
+/// Version: 1.0.0
+/// Platform: iOS (Swift Constants)
+///
+/// Component-specific tokens that reference primitive tokens.
+/// Use these for component-level styling consistency.
+///
+
+import UIKit
+
+/// Avatar Component Tokens
+public enum AvatarTokens {
+    /// Extra small avatar (24px). Compact contexts — inline mentions, dense lists.
+    public static let sizeXs: CGFloat = SizingTokens.size300
+    /// Small avatar (32px). Comment threads, contact lists.
+    public static let sizeSm: CGFloat = SizingTokens.size400
+    /// Medium avatar (40px). Default size — profile cards, list items.
+    public static let sizeMd: CGFloat = SizingTokens.size500
+    /// Large avatar (48px). Profile headers, prominent identity display.
+    public static let sizeLg: CGFloat = SizingTokens.size600
+    /// Extra large avatar (80px). Profile pages, hero sections.
+    public static let sizeXl: CGFloat = SizingTokens.size1000
+    /// Extra extra large avatar (128px). Full profile view, onboarding.
+    public static let sizeXxl: CGFloat = SizingTokens.size1600
+    /// Icon size for xs avatar (12px = 1.5× base) maintains 50% ratio (12/24). No existing icon token at this size, so component token fills the gap.
+    public static let iconSizeXs: CGFloat = 12
+    /// Icon size for xxl avatar (64px = 8× base) maintains 50% ratio (64/128). No existing icon token at this size, so component token fills the gap.
+    public static let iconSizeXxl: CGFloat = 64
+}
+
+/// BadgeLabelBase Component Tokens
+public enum BadgeLabelBaseTokens {
+    /// Maximum width for truncated badges; allows ~12-15 characters before ellipsis while maintaining compact badge appearance. Value follows spacing family pattern (8 × 15 = 120px) but exceeds standard spacing scale, requiring component-level definition.
+    public static let maxWidth: CGFloat = 120
+}
+
+/// ButtonIcon Component Tokens
+public enum ButtonIconTokens {
+    /// Large button variant requires 12px padding (1.5× base) for comfortable touch target and visual balance with larger icon sizes
+    public static let insetLarge: CGFloat = SpacingTokens.space150
+    /// Medium button variant uses 10px padding (1.25× base strategic flexibility token) for compact appearance while maintaining adequate touch area
+    public static let insetMedium: CGFloat = SpacingTokens.space125
+    /// Small button variant uses 8px padding (1× base) for minimal footprint in dense UI layouts while meeting minimum touch target requirements
+    public static let insetSmall: CGFloat = SpacingTokens.space100
+    /// Large button size (48px = 6× base) provides generous touch target exceeding tapAreaRecommended, calculated as icon (24px) + padding (12px × 2)
+    public static let sizeLarge: CGFloat = SpacingTokens.size600
+    /// Medium button size (40px = 5× base) provides standard touch target, calculated as icon (18px) + padding (10px × 2) rounded to grid
+    public static let sizeMedium: CGFloat = SpacingTokens.size500
+    /// Small button size (32px = 4× base) provides compact visual footprint, calculated as icon (13px) + padding (8px × 2) rounded to grid
+    public static let sizeSmall: CGFloat = SpacingTokens.size400
+}
+
+/// InputCheckbox Component Tokens
+public enum InputCheckboxTokens {
+    /// Small checkbox box (24px). icon.size050 (16px) + inset.050 (4px) × 2.
+    public static let boxSm: CGFloat = SizingTokens.size300
+    /// Medium checkbox box (32px). icon.size075 (20px) + inset.075 (6px) × 2.
+    public static let boxMd: CGFloat = SizingTokens.size400
+    /// Large checkbox box (40px). icon.size100 (24px) + inset.100 (8px) × 2.
+    public static let boxLg: CGFloat = SizingTokens.size500
+}
+
+/// InputRadio Component Tokens
+public enum InputRadioTokens {
+    /// Small radio box (24px). Same dimensions as checkbox sm.
+    public static let boxSm: CGFloat = SizingTokens.size300
+    /// Medium radio box (32px). Same dimensions as checkbox md.
+    public static let boxMd: CGFloat = SizingTokens.size400
+    /// Large radio box (40px). Same dimensions as checkbox lg.
+    public static let boxLg: CGFloat = SizingTokens.size500
+}
+
+/// Progress Component Tokens
+public enum ProgressTokens {
+    /// Small node base size (12px). Inactive dots in compact mobile contexts.
+    public static let nodeSizeSm: CGFloat = SpacingTokens.size150
+    /// Medium node base size (16px). Default inactive dot size.
+    public static let nodeSizeMd: CGFloat = SpacingTokens.size200
+    /// Large node base size (20px). Inactive dots in desktop contexts.
+    public static let nodeSizeLg: CGFloat = SpacingTokens.size250
+    /// Current node emphasis for sm (16px). +4px over base 12px for non-color visual differentiation.
+    public static let nodeSizeSmCurrent: CGFloat = SpacingTokens.size200
+    /// Current node emphasis for md (20px). +4px over base 16px for non-color visual differentiation.
+    public static let nodeSizeMdCurrent: CGFloat = SpacingTokens.size250
+    /// Current node emphasis for lg (24px). +4px over base 20px for non-color visual differentiation.
+    public static let nodeSizeLgCurrent: CGFloat = SpacingTokens.size300
+    /// Small gap between nodes (6px = 0.75× base). Tight spacing for compact pagination dots in mobile contexts.
+    public static let nodeGapSm: CGFloat = SpacingTokens.space075
+    /// Medium gap between nodes (8px = 1× base). Default spacing for stepper nodes, providing clear separation without excessive whitespace.
+    public static let nodeGapMd: CGFloat = SpacingTokens.space100
+    /// Large gap between nodes (12px = 1.5× base). Generous spacing for detailed steppers with labels in desktop contexts.
+    public static let nodeGapLg: CGFloat = SpacingTokens.space150
+    /// Connector line thickness (1px). References borderDefault primitive for consistent border treatment across the design system.
+    public static let connectorThickness: CGFloat = SpacingTokens.borderWidth100
+}
+
+/// VerticalListItem Component Tokens
+public enum VerticalListItemTokens {
+    /// Block padding at rest state (1px border). 11px padding + 1px border = 12px per side, achieving 48px total with 24px content. Uses TokenWithValue pattern as no primitive token exists for 11px.
+    public static let paddingBlockRest: CGFloat = 11
+    /// Block padding when selected (2px border). 10px padding + 2px border = 12px per side, maintaining 48px total with 24px content. References space125 strategic flexibility token.
+    public static let paddingBlockSelected: CGFloat = SpacingTokens.space125
+}