dss/.knowledge/FIGMA_SYNC_ARCHITECTURE.md

# Intelligent Figma Sync Architecture

> Deep research synthesis from Figmagic, Design Tokens plugin, Figma MCP patterns, and Gemini 3 Pro analysis.

## Executive Summary

DSS intelligent Figma sync should implement a **4-layer pipeline** architecture with hybrid token extraction, W3C token format compliance, intelligent caching, and strict design contract enforcement.

## Architecture Overview

```
┌─────────────────────────────────────────────────────────────┐
│                    FIGMA API LAYER                          │
├─────────────────────────────────────────────────────────────┤
│  GET /files/{key}           → File metadata, lastModified   │
│  GET /files/{key}/variables → Variables + collections       │
│  GET /files/{key}/styles    → Color, text, effect styles    │
│  GET /files/{key}/nodes     → Component structure           │
│  GET /images/{key}          → Component thumbnails          │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                  VALIDATION LAYER (NEW)                     │
├─────────────────────────────────────────────────────────────┤
│  DesignLinter:                                              │
│    - Reject components without proper variant props         │
│    - Enforce naming conventions (no "Property 1", "Frame X")│
│    - Mark non-compliant as "Raw" (skip code gen)            │
│    - Generate lint report for designers                     │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                  EXTRACTION LAYER                           │
├─────────────────────────────────────────────────────────────┤
│  VariableExtractor  → semantic tokens (color, spacing)      │
│  StyleExtractor     → typography, effects, grids            │
│  ComponentExtractor → component sets, variants, props       │
│  AssetExtractor     → icons, images (optional)              │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│               TRANSLATION LAYER                             │
├─────────────────────────────────────────────────────────────┤
│  FigmaToDSSTranslator:                                      │
│    - Maps Figma naming → DSS canonical names                │
│    - Preserves variable REFERENCES (not resolved values)    │
│    - Normalizes units (px → rem where appropriate)          │
│    - Applies merge strategies (PREFER_FIGMA, LAST, etc)     │
│    - Outputs W3C Design Token format                        │
│    - Separates Visual Props from Interaction States         │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                  OUTPUT LAYER                               │
├─────────────────────────────────────────────────────────────┤
│  TokenWriter    → .dss/data/_system/tokens/figma-tokens.json│
│  ComponentWriter→ .dss/components/figma-registry.json       │
│  StoryGenerator → admin-ui/src/stories/Components/*.stories │
│  CSSGenerator   → .dss/themes/figma.css                     │
└─────────────────────────────────────────────────────────────┘
```

## Key Architectural Decisions

### 1. Hybrid Token Extraction Strategy

| Source | Token Types | Priority |
|--------|-------------|----------|
| Variables | Semantic colors, spacing, breakpoints | Primary |
| Styles | Typography, effects, grids | Secondary |
| Components | UI registry, variants | Tertiary |

**Rationale**: Variables provide modern theming with modes (light/dark), while Styles capture typography which isn't fully available in Variables yet.

### 2. W3C Design Token Format

```json
{
  "$schema": "https://design-tokens.org/schema.json",
  "color": {
    "primary": {
      "$value": "{color.blue.600}",
      "$type": "color",
      "$extensions": {
        "figma": {"styleId": "S:abc123", "source": "variables"}
      }
    }
  }
}
```

**Critical**: Preserve token **references** (`{color.blue.600}`), not resolved values (`#0066cc`). This enables:
- Multi-theme switching (Skins)
- Style Dictionary transformation
- Proper CSS variable generation

### 3. Component Variant Classification

```python
VARIANT_CLASSIFICATION = {
    # Visual Props → React props / Storybook args
    "visual_props": ["Size", "Variant", "Roundness", "Type", "Icon"],

    # Interaction States → CSS pseudo-classes (NOT React props)
    "interaction_states": ["State", "Hover", "Focused", "Pressed", "Disabled"],

    # Boolean toggles → React boolean props
    "boolean_props": ["Checked?", "Selected", "Open", "Expanded"]
}
```

**Example Mapping**:
- Figma: `Button / Primary / Hover / Large`
- Code: `<Button variant="primary" size="large" />`
- CSS handles `:hover` state via pseudo-class

### 4. Canonical Token Interface (CTI)

DSS defines universal tokens that Skins map to:

```
DSS Canonical          →  shadcn Skin           →  HeroUI Skin
─────────────────────────────────────────────────────────────
--dss-action-bg        →  --primary             →  --heroui-primary
--dss-action-fg        →  --primary-foreground  →  --heroui-primary-fg
--dss-surface-bg       →  --background          →  --heroui-background
--dss-muted-bg         →  --muted               →  --heroui-default-100
```

## Intelligent Caching Strategy

### ETag-like Caching

```python
class FigmaSyncCache:
    def should_sync(self, file_key: str) -> bool:
        manifest = self.load_manifest()
        cached = manifest.get(file_key, {})

        # Lightweight API call for lastModified
        remote_modified = self.get_file_version(file_key)

        return (
            cached.get("lastModified") != remote_modified or
            cached.get("age_hours", 999) > 24
        )

    def get_changed_nodes(self, file_key: str) -> list:
        """Compare node hashes to find what changed"""
        local_hashes = self.load_node_hashes(file_key)
        remote_nodes = self.fetch_node_tree(file_key)

        changed = []
        for node_id, node in remote_nodes.items():
            node_hash = hash_node_properties(node)
            if local_hashes.get(node_id) != node_hash:
                changed.append(node_id)

        return changed
```

### Cache Manifest Structure

```json
{
  "evCZlaeZrP7X20NIViSJbl": {
    "lastModified": "2025-12-10T12:00:00Z",
    "syncedAt": "2025-12-10T12:05:00Z",
    "nodeHashes": {
      "66:5034": "abc123...",
      "58:5416": "def456..."
    },
    "extractedTokens": 245,
    "extractedComponents": 67
  }
}
```

## Implementation Priorities

| Priority | Task | Impact | Effort |
|----------|------|--------|--------|
| **P0** | Rate limit handling (exponential backoff, request queue) | Critical | Low |
| **P0** | lastModified caching check | High | Low |
| **P1** | Variable extraction (Figma Variables API) | High | Medium |
| **P1** | Translation layer (Figma → DSS canonical) | High | Medium |
| **P1** | Design validation/linting | Medium | Medium |
| **P2** | Incremental node-level sync | Medium | High |
| **P2** | W3C token output format | Medium | Low |
| **P3** | Storybook story generation with variant controls | Medium | Medium |
| **P3** | Asset extraction (icons, images) | Low | Low |

## Design Contract Enforcement

**Principle**: Don't write complex code to handle messy design. Enforce design standards.

### Required Variant Properties

Components must have properly named variant properties to be eligible for code generation:

```
✓ Valid:   Button[Size=Large, Variant=Primary, State=Hover]
✗ Invalid: Button[Property 1=true, Frame 4221]
```

### Naming Convention Rules

1. Variant properties: PascalCase (`Size`, `Variant`, `State`)
2. Variant values: PascalCase (`Large`, `Primary`, `Hover`)
3. No auto-generated names (`Property 1`, `Frame 123`)
4. Boolean variants: End with `?` (`Checked?`, `Selected?`)

## File Outputs

| File | Purpose | Format |
|------|---------|--------|
| `.dss/data/_system/tokens/figma-variables.json` | Raw Figma variables | W3C Token |
| `.dss/data/_system/tokens/figma-styles.json` | Typography & effects | W3C Token |
| `.dss/components/figma-registry.json` | Component catalog | DSS Registry |
| `.dss/cache/figma-sync-manifest.json` | Sync state cache | Internal |
| `.dss/logs/figma-lint-report.json` | Design validation | Report |

## Research Sources

- [Figmagic](https://github.com/mikaelvesavuori/figmagic) - Design token extraction patterns
- [Design Tokens Plugin](https://github.com/lukasoppermann/design-tokens) - W3C format, Style Dictionary integration
- [Tokens Studio](https://docs.tokens.studio) - Variable aliasing, theming
- [Figma MCP](https://www.seamgen.com/blog/figma-mcp-complete-guide-to-design-to-code-automation) - AI-assisted code generation
- [Figma Developer API](https://www.figma.com/developers/api) - Official documentation

## Next Steps

1. **Implement P0 items**: Rate limiting and caching
2. **Create token-map.json**: Bridge between Figma IDs and DSS canonical names
3. **Build validation layer**: Design linting before extraction
4. **Test with Obra shadcn UIKit**: Validate against real Figma file