Initial commit: Clean DSS implementation

Migrated from design-system-swarm with fresh git history. Old project history preserved in /home/overbits/apps/design-system-swarm Core components: - MCP Server (Python FastAPI with mcp 1.23.1) - Claude Plugin (agents, commands, skills, strategies, hooks, core) - DSS Backend (dss-mvp1 - token translation, Figma sync) - Admin UI (Node.js/React) - Server (Node.js/Express) - Storybook integration (dss-mvp1/.storybook) Self-contained configuration: - All paths relative or use DSS_BASE_PATH=/home/overbits/dss - PYTHONPATH configured for dss-mvp1 and dss-claude-plugin - .env file with all configuration - Claude plugin uses ${CLAUDE_PLUGIN_ROOT} for portability Migration completed: $(date) 🤖 Clean migration with full functionality preserved
2025-12-09 18:45:48 -03:00
commit 276ed71f31
884 changed files with 373737 additions and 0 deletions
--- a/dss-claude-plugin/skills/figma-sync/SKILL.md
+++ b/dss-claude-plugin/skills/figma-sync/SKILL.md
@@ -0,0 +1,188 @@
+---
+name: Figma Sync
+description: Synchronize design tokens from Figma files using the Figma API
+globs:
+  - "**/figma-tokens/**"
+  - "**/design-tokens/**"
+  - "**/*.figma.json"
+alwaysApply: false
+---
+
+# Figma Sync
+
+## Overview
+
+This skill enables synchronization of design tokens from Figma files. It extracts colors, typography, spacing, and other design decisions from Figma and converts them to code-ready tokens.
+
+## When to Use
+
+Use this skill when the user asks to:
+- Import tokens from Figma
+- Sync design decisions with code
+- Extract colors from Figma file
+- Update tokens from Figma changes
+- Connect Figma to the design system
+
+## Prerequisites
+
+### Figma Token
+Set the `FIGMA_TOKEN` environment variable:
+```bash
+export FIGMA_TOKEN=your-figma-personal-access-token
+```
+
+### File Key
+Get the file key from Figma URL:
+```
+https://www.figma.com/file/XXXXXXXXXXXXXX/Design-System
+                            ^^^^^^^^^^^^^^
+                            This is the file key
+```
+
+## Extracted Token Types
+
+| Type | Figma Source | Token Output |
+|------|--------------|--------------|
+| Colors | Fill colors, Strokes | color.* tokens |
+| Typography | Text styles | typography.* tokens |
+| Spacing | Auto-layout gaps | spacing.* tokens |
+| Shadows | Drop shadows | shadow.* tokens |
+| Radii | Corner radius | radius.* tokens |
+| Borders | Stroke weights | border.* tokens |
+
+## Workflow
+
+1. **Get Figma File Key**
+   - Open Figma file in browser
+   - Copy file key from URL
+
+2. **Sync Tokens**
+   ```
+   Use dss_sync_figma with file_key
+   ```
+
+3. **Review Extracted Tokens**
+   - Check token names
+   - Verify values
+   - Review categories
+
+4. **Generate Theme Files**
+   - Use theme generation skill
+   - Export to CSS/SCSS/JSON
+
+## Example Interaction
+
+**User:** "Sync design tokens from our Figma file"
+
+**Assistant Response:**
+```
+I'll sync tokens from your Figma file.
+
+First, I need the Figma file key. You can find it in the URL:
+https://www.figma.com/file/[FILE_KEY]/Design-System
+
+What's your file key?
+
+**User:** abc123xyz456
+
+[Uses dss_sync_figma with file_key: abc123xyz456]
+
+**Figma Sync Results:**
+
+**Extracted Tokens:**
+
+Colors (24 tokens):
+- primary/500: #0066CC
+- primary/400: #3385D6
+- primary/600: #0052A3
+- secondary/500: #6C757D
+- success/500: #28A745
+- error/500: #DC3545
+
+Typography (8 styles):
+- heading/h1: Inter Bold 48px/56px
+- heading/h2: Inter Bold 36px/44px
+- heading/h3: Inter SemiBold 24px/32px
+- body/regular: Inter Regular 16px/24px
+- body/small: Inter Regular 14px/20px
+
+Spacing (6 values):
+- xs: 4px
+- sm: 8px
+- md: 16px
+- lg: 24px
+- xl: 32px
+- 2xl: 48px
+
+Shadows (3 styles):
+- sm: 0 1px 2px rgba(0,0,0,0.05)
+- md: 0 4px 6px rgba(0,0,0,0.1)
+- lg: 0 10px 15px rgba(0,0,0,0.1)
+
+**Total:** 41 tokens extracted
+
+Would you like me to generate theme files from these tokens?
+```
+
+## API Rate Limiting
+
+The Figma API has rate limits:
+- 30 requests per minute for free plans
+- Higher limits for paid plans
+
+DSS implements:
+- Automatic retry with exponential backoff
+- Request caching (1 hour TTL)
+- Batch requests where possible
+
+## Token Naming
+
+Figma names are converted to token format:
+```
+Figma: "Primary / 500"
+Token: color-primary-500
+
+Figma: "Heading / H1"
+Token: typography-heading-h1
+
+Figma: "Shadow / Medium"
+Token: shadow-md
+```
+
+## Error Handling
+
+| Error | Cause | Solution |
+|-------|-------|----------|
+| 403 Forbidden | Invalid token | Check FIGMA_TOKEN |
+| 404 Not Found | Invalid file key | Verify file key |
+| 429 Too Many Requests | Rate limited | Wait and retry |
+
+## Related Tools
+
+- `dss_sync_figma` - Main sync tool
+- `dss_extract_tokens` - Merge with other sources
+- `dss_generate_theme` - Generate from Figma tokens
+
+## Best Practices
+
+1. **Figma Organization**
+   - Use consistent naming in Figma
+   - Organize styles in folders
+   - Use descriptions for context
+
+2. **Sync Frequency**
+   - Sync after major design changes
+   - Automate in CI/CD if possible
+   - Version control token files
+
+3. **Conflict Resolution**
+   - Compare with existing tokens
+   - Review changes before applying
+   - Maintain changelog
+
+## Security Notes
+
+- Never commit FIGMA_TOKEN to version control
+- Use environment variables or secrets manager
+- Rotate tokens periodically
+- Use read-only tokens when possible