feat: Add DSS infrastructure, remove legacy admin-ui code

- Remove legacy admin-ui/js/ vanilla JS components - Add .dss/ directory with core tokens, skins, themes - Add Storybook configuration and generated stories - Add DSS management scripts (dss-services, dss-init, dss-setup, dss-reset) - Add MCP command definitions for DSS plugin - Add Figma sync architecture and scripts - Update pre-commit hooks with documentation validation - Fix JSON trailing commas in skin files 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-12-10 22:15:11 -03:00
parent 71c6dc805a
commit 08ce228df1
205 changed files with 65666 additions and 47577 deletions
--- a/.knowledge/DSS_CORE.json
+++ b/.knowledge/DSS_CORE.json
@@ -1,6 +1,6 @@
 {
  "$schema": "dss-core-v1",
-  "version": "1.1.0",
+  "version": "1.3.0",
  "last_updated": "2025-12-10",
  "purpose": "Single source of truth for AI agents working with DSS",

@@ -24,7 +24,7 @@

  "canonical_structure": {
    "tokens": ["colors", "spacing", "typography", "borders", "shadows", "motion"],
-    "components": ["Button", "Input", "Card", "Badge", "Toast", "..."],
+    "components": "59 shadcn/ui components - see .dss/components/shadcn-registry.json",
    "patterns": ["forms", "navigation", "layouts"],
    "rule": "This structure NEVER changes. All inputs normalize to this."
  },
@@ -87,6 +87,57 @@
    "context_compiler": ["dss_get_resolved_context", "dss_get_compiler_status"]
  },

+  "token_architecture": {
+    "description": "3-Layer Token Cascade with Skin Contract validation",
+    "layers": {
+      "1_core_primitives": {
+        "path": ".dss/core/primitives.json",
+        "purpose": "Raw Tailwind-style values (colors, spacing, radius, fonts)",
+        "immutable": true,
+        "shared": "Across all skins"
+      },
+      "2_skin": {
+        "path": ".dss/skins/{skin_name}/tokens.json",
+        "purpose": "Semantic mapping from primitives to design tokens",
+        "contract": ".dss/schema/skin-contract.json",
+        "examples": ["shadcn", "heroui", "material"],
+        "rule": "Must provide ALL tokens defined in skin-contract"
+      },
+      "3_theme": {
+        "path": ".dss/themes/{theme_name}.json",
+        "purpose": "Brand overrides on top of skin",
+        "rule": "May ONLY override tokens defined in skin-contract",
+        "survives": "Skin updates (stable API through contract)"
+      }
+    },
+    "cascade_flow": "Core Primitives -> Skin (semantic) -> Theme (brand) = Final Tokens",
+    "validation": {
+      "script": "scripts/validate-theme.py",
+      "checks": [
+        "Skin provides all contract-required tokens",
+        "Theme only overrides contract tokens"
+      ]
+    },
+    "resolution": {
+      "script": "scripts/resolve-tokens.py",
+      "output": ".dss/data/_system/tokens/tokens.json",
+      "resolves": "Token references like {color.zinc.500} using primitives"
+    },
+    "storybook_generation": {
+      "script": "scripts/generate-storybook.py",
+      "output": "admin-ui/src/stories/",
+      "generates": [
+        "Overview.stories.js - Introduction and architecture",
+        "ColorPrimitives.stories.js - Tailwind color palette",
+        "Spacing.stories.js - Spacing scale",
+        "Radius.stories.js - Border radius tokens",
+        "Typography.stories.js - Typography styles from Figma",
+        "Effects.stories.js - Shadows and focus rings",
+        "SemanticColors.stories.js - Semantic color tokens from skin"
+      ]
+    }
+  },
+
  "context_compiler": {
    "cascade": "Base Skin -> Extended Skin -> Project Overrides = Final Context",
    "caching": "mtime-based invalidation",
@@ -114,7 +165,16 @@
    "skills": "dss-claude-plugin/skills/",
    "commands": "dss-claude-plugin/commands/",
    "logs": ".dss/logs/",
-    "cache": ".dss/cache/"
+    "cache": ".dss/cache/",
+    "core_primitives": ".dss/core/primitives.json",
+    "skin_contract": ".dss/schema/skin-contract.json",
+    "skins": ".dss/skins/",
+    "themes": ".dss/themes/",
+    "token_resolver": "scripts/resolve-tokens.py",
+    "theme_validator": "scripts/validate-theme.py",
+    "storybook_generator": "scripts/generate-storybook.py",
+    "storybook_stories": "admin-ui/src/stories/",
+    "component_registry": ".dss/components/shadcn-registry.json"
  },

  "coding_rules_summary": {
@@ -222,7 +282,27 @@
    "cli": "dss ingest --source figma --file tokens.json"
  },

+  "component_registry": {
+    "path": ".dss/components/shadcn-registry.json",
+    "source": "shadcn/ui (https://ui.shadcn.com)",
+    "total_components": 59,
+    "categories": {
+      "form": "21 components (Button, Input, Select, Checkbox, etc.)",
+      "data-display": "11 components (Table, Badge, Avatar, Chart, etc.)",
+      "feedback": "7 components (Alert, Toast, Progress, Spinner, etc.)",
+      "navigation": "6 components (Tabs, Breadcrumb, Sidebar, etc.)",
+      "overlay": "9 components (Dialog, Sheet, Dropdown, Tooltip, etc.)",
+      "layout": "5 components (Card, Separator, Scroll Area, etc.)"
+    },
+    "dependencies": {
+      "radix": "26 Radix UI primitives",
+      "additional": ["cmdk", "embla-carousel", "react-day-picker", "recharts", "sonner", "vaul"]
+    }
+  },
+
  "changelog": [
+    {"version": "1.3.0", "date": "2025-12-10", "notes": "Add 59-component shadcn registry, expand primitives to full Tailwind palette"},
+    {"version": "1.2.0", "date": "2025-12-10", "notes": "Add 3-layer token architecture with skin contract validation"},
    {"version": "1.1.0", "date": "2025-12-10", "notes": "Migrate from SQLite to JSON file storage"},
    {"version": "1.0.0", "date": "2025-12-10", "notes": "Initial core definition"}
  ]
--- a/.knowledge/FIGMA_SYNC_ARCHITECTURE.md
+++ b/.knowledge/FIGMA_SYNC_ARCHITECTURE.md
@@ -0,0 +1,236 @@
+# 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