appiq-solution 1.2.0 → 1.3.1

package/#Tools/claude-talk-to-figma-mcp/prompts/prompt-ux-ui-especialista-pt.md

@@ -0,0 +1,80 @@
+# Especialista Sénior em Design UX/UI
+
+Atua como um especialista sénior em Design UX/UI com mais de 10 anos de experiência em design centrado no utilizador, investigação de utilizadores, criação de protótipos interativos e sistemas de design. A tua especialidade é criar interfaces digitais intuitivas, acessíveis e atrativas utilizando as mais recentes metodologias e ferramentas do setor.
+
+Para cada consulta ou solicitação que te faça, segue este processo estruturado de 4 passos:
+
+## 1. ANÁLISE
+- Analisa detalhadamente o meu pedido de design
+- Identifica as necessidades dos utilizadores e objetivos do negócio
+- Determina as restrições técnicas e de acessibilidade
+- Considera os compromissos entre estética, usabilidade e viabilidade técnica
+
+## 2. PRINCÍPIOS
+- Explica os princípios de design UX/UI relevantes para este caso
+- Identifica padrões de interação aplicáveis (navegação, introdução de dados, feedback)
+- Menciona as melhores práticas de design centrado no utilizador
+- Destaca considerações de acessibilidade, consistência e escalabilidade visual
+
+## 3. SOLUÇÕES
+- Fornece wireframes conceptuais ou descrições específicas quando necessário
+- Explica a estrutura de navegação e arquitetura de informação recomendada
+- Detalha o processo de design passo a passo
+- Inclui exemplos concretos de elementos UI com explicações de design
+- Sugere ferramentas ou recursos complementares se necessários
+
+## 4. CONCLUSÕES
+- Resume os pontos-chave da solução de design
+- Sugere próximos passos (testes, iteração, implementação)
+- Antecipa possíveis desafios de usabilidade e como abordá-los
+- Oferece recursos adicionais de UX/UI se relevantes
+
+## FORMATO DE RESPOSTA
+Todas as tuas respostas devem seguir esta estrutura específica:
+
+```
+📋 RESUMO DO REQUISITO
+[Breve descrição do que solicitei]
+
+🔍 ANÁLISE
+[Aplicar o passo 1 detalhadamente]
+
+🧩 PRINCÍPIOS
+[Aplicar o passo 2 detalhadamente]
+
+⚙️ SOLUÇÃO
+[Aplicar o passo 3 detalhadamente, incluindo representações visuais quando possível]
+
+🏁 CONCLUSÃO
+[Aplicar o passo 4 detalhadamente]
+
+❓ PERGUNTAS DE CLARIFICAÇÃO (opcional)
+[Quaisquer perguntas que precises para entender melhor os meus requisitos]
+```
+
+## CONHECIMENTOS ESPECÍFICOS
+Deves ter conhecimento especializado em:
+- Metodologias de Design Thinking e Human-Centered Design
+- Investigação de utilizadores (entrevistas, testes de usabilidade, inquéritos)
+- Wireframing e prototipagem com Figma, Adobe XD e Sketch
+- Sistemas de design e bibliotecas de componentes
+- Princípios de Gestalt e teoria da cor
+- Design responsivo e mobile-first
+- Tipografia digital e hierarquia visual
+- Acessibilidade web (WCAG 2.1) e inclusividade
+- Micro-interações e animações de interface
+- Avaliação heurística e auditorias de UX
+- Mapas de experiência do utilizador e customer journeys
+- Arquitetura de informação e padrões de navegação
+- Design de formulários e processos de conversão
+- Tendências atuais em design de interfaces
+- Colaboração com desenvolvedores e handoff de design
+- A/B testing e otimização iterativa
+
+## COMPORTAMENTO ESPERADO
+- Sê conciso mas completo nas tuas explicações de design
+- Fornece soluções que sigam os princípios de UX/UI modernos
+- Considera sempre a acessibilidade, usabilidade e valor para o utilizador
+- Explica os conceitos de design de maneira clara e visual
+- Sugere alternativas quando apropriado
+- Quando não tiveres a certeza sobre algo, indica-o claramente

package/#Tools/claude-talk-to-figma-mcp/prompts/prompt-ux-ui-specialist.md

@@ -0,0 +1,80 @@
+# Senior UX/UI Design Specialist
+
+Act as a senior UX/UI Design specialist with over 10 years of experience in user-centered design, user research, interactive prototyping, and design systems. Your specialty is creating intuitive, accessible, and attractive digital interfaces using the latest methodologies and tools in the industry.
+
+For each query or request I make, follow this structured 4-step process:
+
+## 1. ANALYSIS
+- Analyze my design request in detail
+- Identify user needs and business objectives
+- Determine technical and accessibility constraints
+- Consider trade-offs between aesthetics, usability, and technical feasibility
+
+## 2. PRINCIPLES
+- Explain the UX/UI design principles relevant to this case
+- Identify applicable interaction patterns (navigation, data entry, feedback)
+- Mention best practices in user-centered design
+- Highlight considerations for accessibility, consistency, and visual scalability
+
+## 3. SOLUTIONS
+- Provide conceptual wireframes or specific descriptions when necessary
+- Explain the recommended navigation structure and information architecture
+- Detail the design process step by step
+- Include concrete examples of UI elements with design explanations
+- Suggest complementary tools or resources if needed
+
+## 4. CONCLUSIONS
+- Summarize the key points of the design solution
+- Suggest next steps (testing, iteration, implementation)
+- Anticipate potential usability challenges and how to address them
+- Offer additional UX/UI resources if relevant
+
+## RESPONSE FORMAT
+All your responses must follow this specific structure:
+
+```
+📋 REQUIREMENT SUMMARY
+[Brief description of what I've requested]
+
+🔍 ANALYSIS
+[Apply step 1 in detail]
+
+🧩 PRINCIPLES
+[Apply step 2 in detail]
+
+⚙️ SOLUTION
+[Apply step 3 in detail, including visual representations when possible]
+
+🏁 CONCLUSION
+[Apply step 4 in detail]
+
+❓ CLARIFICATION QUESTIONS (optional)
+[Any questions you need to better understand my requirements]
+```
+
+## SPECIFIC KNOWLEDGE
+You must have expert knowledge in:
+- Design Thinking methodologies and Human-Centered Design
+- User research (interviews, usability testing, surveys)
+- Wireframing and prototyping with Figma, Adobe XD, and Sketch
+- Design systems and component libraries
+- Gestalt principles and color theory
+- Responsive and mobile-first design
+- Digital typography and visual hierarchy
+- Web accessibility (WCAG 2.1) and inclusivity
+- Micro-interactions and interface animations
+- Heuristic evaluation and UX audits
+- User experience maps and customer journeys
+- Information architecture and navigation patterns
+- Form design and conversion processes
+- Current trends in interface design
+- Collaboration with developers and design handoff
+- A/B testing and iterative optimization
+
+## EXPECTED BEHAVIOR
+- Be concise but complete in your design explanations
+- Provide solutions that follow modern UX/UI principles
+- Always consider accessibility, usability, and value for the user
+- Explain design concepts clearly and visually
+- Suggest alternatives when appropriate
+- When you're not sure about something, indicate it clearly

package/#Tools/claude-talk-to-figma-mcp/readme.md

@@ -0,0 +1,307 @@
+<img src="images/claude-talk-to-figma.png" alt="Claude Talk to Figma collage" />
+
+# Claude Talk to Figma MCP
+
+A Model Context Protocol (MCP) plugin that allows Claude Desktop and other AI tools (GitHub Copilot, Cursor, etc.) to interact directly with Figma, enabling powerful AI-assisted design capabilities.
+
+> **Important**: This project is based on [cursor-talk-to-figma-mcp](https://github.com/sonnylazuardi/cursor-talk-to-figma-mcp) by Sonny Lazuardi. It has been adapted to work with Claude Desktop instead of Cursor and the modification tools have been expanded. The original implementation and main credit belongs to Sonny Lazuardi ❤️
+
+## 🚀 Features
+
+- **Native Claude Integration**: Allows Claude to communicate with Figma through the Model Context Protocol (MCP)
+- **Powerful Commands**: Manipulate objects in Figma, get information, create and modify elements
+- **Advanced Text & Font Control**: Comprehensive text styling capabilities including font selection, spacing, and text effects
+- **Bidirectional Communication**: Real-time WebSocket channel between Claude and Figma
+- **Fluid Experience**: Design with AI as your assistant, accelerating creative workflows
+- **Text Scanning**: Identify and manipulate text nodes within Figma documents
+- **Remote Components**: Access and utilize components from team libraries
+- **Modular Architecture**: Clean separation of concerns with specialized tool modules
+- **Enhanced Error Handling**: Robust timeout and error recovery mechanisms
+- **Performance Optimizations**: Improved handling of complex operations with chunking and batching
+
+## 📋 Prerequisites
+
+- [Claude Desktop](https://claude.ai/download) installed
+- [Figma Desktop](https://www.figma.com/downloads/) installed
+- [Figma](https://figma.com) account
+- [Bun](https://bun.sh) v1.0.0 or higher 
+  - Linux macOS ```curl -fsSL https://bun.sh/install | bash```
+  - Windows ```powershell -c "irm bun.sh/install.ps1 | iex"```
+
+## ⚙️ Installation
+
+1. Clone this repository:
+   ```bash
+   git clone https://github.com/arinspunk/claude-talk-to-figma-mcp.git
+   cd claude-talk-to-figma-mcp
+   ```
+
+2. Install dependencies:
+   ```bash
+   bun install
+   ```
+
+3. Build the project:
+   ```bash
+   bun run build
+   ```
+
+4. Configure the MCP in Claude Desktop:
+   ```bash
+   bun run configure-claude
+   ```
+   Restart Claude Desktop if it was open.
+
+   > **Note**: This script does the following:
+   
+   - Locates the Claude Desktop configuration file:
+     - On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+     - On Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+   - Creates a backup of the existing configuration file
+   - Modifies or creates the configuration file to include "ClaudeTalkToFigma" in the list of MCPs
+   - Configures the command that Claude Desktop should execute to start the MCP
+
+5. Install the Figma plugin:
+   
+   > **Note**: This project uses a custom Figma plugin located in the `src/claude_mcp_plugin` folder.
+
+   - Open Figma
+   - Go to **Menu > Plugins > Development**
+   - Select "Import plugin from manifest"
+   - Navigate and select the `src/claude_mcp_plugin/src/claude_mcp_plugin/manifest.json` file from this repository
+
+   The plugin will appear in your development plugins list and you can use it like any other plugin.
+
+## 🚀 Usage
+
+### 🔌 Starting Up
+
+Once installed, you just need to start it:
+
+1. **Start the WebSocket server**:
+   ```bash
+   bun socket
+   ```
+   Verify it's running with `http://localhost:3055/status`
+   
+   > **Note**: if for any reason you need to stop the server, press `Ctrl+C` in the terminal.
+
+3. **Connect the plugin to the server**:
+
+   Open the Claude MCP Plugin in Figma and copy the channel ID generated to provide it to Claude.
+
+   <img src="images/mcp-figma-plugin-configuration.png" width="300" alt="Figma Plugin Configuration" />
+
+4. **Claude Desktop**:
+
+   Open Claude Desktop and confirm that "ClaudeTalkToFigma" appears in the MCPs selector.
+
+5. **Ready to use!**
+
+   Now you can send commands to Figma from Claude.
+
+### 🧠 Prompting
+
+1. Before you start designing with Claude, [make it an expert in UX/UI](prompts/prompt-ux-ui-specialist.md) 🎨
+   
+   > **Note**: Also in [Galician](prompts/prompt-ux-ui-especialista-gal.md), [Português](prompts/prompt-ux-ui-especialista-pt.md) and [Español](prompts/prompt-ux-ui-especialista-es.md).
+
+2. Now tell Claude to connect to your Figma project:
+   ```
+   Talk to Figma, channel {channel-ID}
+   ```
+
+## 🏛️ Architecture
+
+```
++----------------+     +-------+     +---------------+     +---------------+
+|                |     |       |     |               |     |               |
+| Claude Desktop |<--->|  MCP  |<--->| WebSocket Srv |<--->| Figma Plugin  |
+|   (AI Agent)   |     |       |     |  (Port 3055)  |     |  (UI Plugin)  |
+|                |     |       |     |               |     |               |
++----------------+     +-------+     +---------------+     +---------------+
+```
+
+### Design Principles
+
+The system follows a clear separation of concerns:
+
+- **MCP Server**: Handles business logic, validation, and default values
+- **WebSocket Server**: Routes messages between components  
+- **Figma Plugin**: Pure translator that executes commands in Figma
+
+This approach ensures that each layer has a single responsibility, making the system more reliable and easier to maintain.
+
+### Project Structure
+
+```
+src/
+  talk_to_figma_mcp/     # MCP Server implementation
+    server.ts            # Main entry point
+    config/              # Server configuration
+    tools/               # Tool categories by function
+      index.ts           # Tool registration
+      document-tools.ts  # Document interaction tools
+      creation-tools.ts  # Shape and element creation tools
+      modification-tools.ts # Property modification tools
+      text-tools.ts      # Text manipulation tools
+      component-tools.ts # Component handling tools
+    utils/               # Shared utilities and helpers
+      defaults.ts        # Safe default value handling
+      websocket.ts       # WebSocket communication
+      logger.ts          # Logging system
+      figma-helpers.ts   # Figma-specific helpers
+    types/               # TypeScript type definitions
+      color.ts           # Color type definitions
+  claude_mcp_plugin/     # Figma plugin
+    code.js              # Plugin implementation
+    manifest.json        # Plugin configuration
+    ui.html              # Plugin UI
+```
+
+Benefits of this structure:
+- **Clear ownership**: Each component has well-defined responsibilities
+- **Easy testing**: Components can be tested in isolation
+- **Maintainable**: Changes to one layer don't affect others
+
+## 🛠️ Available Commands
+
+As Claude is connected to our MCP, it already knows the list of tools to manipulate Figma. But if you want, you can mention them in your prompts:  
+
+### Document Tools
+- `get_document_info`: Get detailed information about the current Figma document
+- `get_selection`: Get information about the current selection in Figma
+- `get_node_info`: Get detailed information about a specific node in Figma
+- `get_nodes_info`: Get detailed information about multiple nodes in Figma
+- `get_styles`: Get all styles from the current Figma document
+- `get_local_components`: Get all local components from the Figma document
+- `get_remote_components`: Get available components from team libraries in Figma
+- `scan_text_nodes`: Scan all text nodes in the selected Figma node
+- `join_channel`: Join a specific channel to communicate with Figma
+- `export_node_as_image`: Export a node as an image from Figma
+
+### Creation Tools
+- `create_rectangle`: Create a new rectangle in Figma
+- `create_frame`: Create a new frame in Figma
+- `create_text`: Create a new text element in Figma
+- `create_ellipse`: Create a new ellipse or circle in Figma
+- `create_polygon`: Create a new polygon with customizable sides in Figma
+- `create_star`: Create a new star with customizable points in Figma
+- `create_vector`: Create a new vector shape in Figma
+- `create_line`: Create a new line in Figma
+- `group_nodes`: Group multiple nodes together in Figma
+- `ungroup_nodes`: Ungroup nodes in Figma
+- `clone_node`: Clone an existing node in Figma
+- `insert_child`: Insert a child node inside a parent node in Figma
+- `flatten_node`: Flatten a node in Figma (e.g., for boolean operations)
+
+### Modification Tools
+- `set_fill_color`: Set the fill color of a node in Figma
+- `set_stroke_color`: Set the stroke color of a node in Figma
+- `move_node`: Move a node to a new position in Figma
+- `resize_node`: Resize a node in Figma
+- `delete_node`: Delete a node from Figma
+- `set_corner_radius`: Set the corner radius of a node in Figma
+- `set_auto_layout`: Configure auto layout properties for a node in Figma
+- `set_effects`: Set visual effects (shadows, blurs) for a node in Figma
+- `set_effect_style_id`: Apply an effect style to a node in Figma
+
+### Text Tools
+- `set_text_content`: Set the text content of an existing text node in Figma
+- `set_multiple_text_contents`: Set multiple text contents parallelly in a node
+- `set_font_name`: Set the font name and style of a text node in Figma
+- `set_font_size`: Set the font size of a text node in Figma
+- `set_font_weight`: Set the font weight of a text node in Figma
+- `set_letter_spacing`: Set the letter spacing of a text node in Figma
+- `set_line_height`: Set the line height of a text node in Figma
+- `set_paragraph_spacing`: Set the paragraph spacing of a text node in Figma
+- `set_text_case`: Set the text case of a text node in Figma
+- `set_text_decoration`: Set the text decoration of a text node in Figma
+- `get_styled_text_segments`: Get text segments with specific styling in a text node
+- `load_font_async`: Load a font asynchronously in Figma
+
+### Component Tools
+- `create_component_instance`: Create an instance of a component in Figma
+
+## 📝 CHANGELOG
+
+See [CHANGELOG.md](CHANGELOG.md) for a detailed history of changes.
+
+### Current version: 0.5.2
+
+- **Critical Bug Fixes**: Fixed opacity and stroke weight handling in `set_stroke_color` where falsy values were incorrectly converted
+- **Architectural Improvements**: Extended safe defaults pattern across all color operations with consistent MCP/Plugin separation
+- **Enhanced Testing**: Comprehensive test coverage for stroke operations and edge cases
+- **Code Quality**: Improved type safety, validation, and error handling throughout the system
+
+For more details about previous and complete changes, check the [CHANGELOG.md](CHANGELOG.md).
+
+## 🐛 Troubleshooting
+
+If you encounter problems, check the following common issues:
+
+### Common Issues
+
+- **Connection Error**: Make sure the WebSocket server is running with `bun socket`
+- **Plugin Not Appearing**: Verify that you've correctly linked the plugin folder in Figma Development settings
+- **Claude Can't Find the MCP**: Make sure you've run `bun run configure-claude` and restarted Claude Desktop
+- **Claude Not Responding**: Confirm you've selected "ClaudeTalkToFigma" in the MCPs menu
+- **Execution Errors**: Check the Figma development console for detailed messages
+- **Font Loading Issues**: Some fonts might not be available in Figma. Use `load_font_async` to verify font availability
+- **Remote Components Error**: Team libraries might require proper permissions in Figma. Ensure you have access to the libraries you're trying to use
+
+## 🧪 Testing
+
+The project includes two complementary testing approaches:
+
+### Automated Tests
+
+For unit and component integration tests:
+
+```bash
+bun run test            # Run all automated tests
+bun run test:watch      # Run tests in watch mode
+bun run test:coverage   # Run tests with coverage report
+```
+
+### Manual Integration Tests
+
+For end-to-end functionality testing between Claude, WebSocket server, and Figma:
+
+```bash
+bun run test:integration
+```
+
+This script guides you through testing the complete integration workflow.
+
+For more comprehensive testing documentation, see [TESTING.md](TESTING.md).
+
+## 🤝 Contributions
+
+Contributions are welcome. Please follow these steps:
+
+1. Fork the repository
+2. Create a branch for your feature (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+### Contributors
+
+- **[Taylor Smits](https://github.com/smitstay)** - Fixed opacity handling in color functions and added automated tests ([PR #13](https://github.com/arinspunk/claude-talk-to-figma-mcp/pull/13), [PR #14](https://github.com/arinspunk/claude-talk-to-figma-mcp/pull/14))
+
+## 📄 License
+
+This project is under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## 👥 Authors
+
+- **Xúlio Zé** - *Adaptation for Claude* - [GitHub](https://github.com/arinspunk)
+- **Sonny Lazuardi** - *Original Cursor implementation* - [GitHub](https://github.com/sonnylazuardi)
+
+## 🙏 Acknowledgments
+
+- Anthropic team for Claude and the Model Context Protocol
+- Figma community for their excellent plugin API
+- Sonny Lazuardi for the original Cursor Talk to Figma MCP implementation
+- Bun team for providing a fast JavaScript runtime

package/#Tools/claude-talk-to-figma-mcp/scripts/configure-claude.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { execSync } from 'child_process';
+import { fileURLToPath } from 'url';
+
+// Get current file directory (ES modules don't have __dirname)
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Determine the location of Claude Desktop configuration file
+const configPath = os.platform() === 'darwin' 
+  ? path.join(os.homedir(), 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json')
+  : path.join(os.homedir(), 'AppData', 'Roaming', 'Claude', 'claude_desktop_config.json');
+
+// Get the absolute path of package.json
+const packageJsonPath = path.join(__dirname, '..', 'package.json');
+const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+const packageName = packageJson.name;
+const packageVersion = packageJson.version;
+
+console.log(`Configuring Claude Desktop for ${packageName} v${packageVersion}...`);
+
+// Create backups
+function backupFile(filePath) {
+  if (fs.existsSync(filePath)) {
+    const backupPath = `${filePath}.backup-${Date.now()}`;
+    fs.copyFileSync(filePath, backupPath);
+    console.log(`Backup created at: ${backupPath}`);
+  }
+}
+
+// Read existing configuration or create new one
+let config = {};
+try {
+  if (fs.existsSync(configPath)) {
+    config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    console.log('Existing configuration found.');
+    backupFile(configPath);
+  } else {
+    console.log('No existing configuration found. Creating new one.');
+    
+    // Create required directories if they don't exist
+    const configDir = path.dirname(configPath);
+    if (!fs.existsSync(configDir)) {
+      fs.mkdirSync(configDir, { recursive: true });
+      console.log(`Directory created: ${configDir}`);
+    }
+  }
+} catch (e) {
+  console.error(`Error reading existing configuration: ${e.message}`);
+  console.error('Creating new configuration.');
+}
+
+// Check if bun is installed
+let useBun = false;
+try {
+  execSync('bun --version', { stdio: 'ignore' });
+  useBun = true;
+  console.log('Bun detected on the system.');
+} catch (e) {
+  console.log('Bun is not installed. Using npx as an alternative.');
+}
+
+// Add MCP configuration
+config.mcpServers = config.mcpServers || {};
+config.mcpServers['ClaudeTalkToFigma'] = {
+  command: 'npx',
+  args: [`${packageName}@latest`]
+};
+
+console.log('Updated configuration for ClaudeTalkToFigma:');
+console.log(JSON.stringify(config.mcpServers['ClaudeTalkToFigma'], null, 2));
+
+// Write configuration
+try {
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2));
+  console.log(`Configuration saved to ${configPath}`);
+  console.log('\nConfiguration completed successfully.');
+  console.log('\nTo use this MCP in Claude Desktop:');
+  console.log('1. Restart Claude Desktop if it\'s running');
+  console.log('2. Open Claude Desktop and select "ClaudeTalkToFigma" from the MCPs list');
+  console.log(`3. Start the WebSocket server: npx ${packageName}-socket`);
+  console.log('4. Install and run the Figma plugin');
+} catch (e) {
+  console.error(`Error writing configuration: ${e.message}`);
+  console.error(`Make sure you have write permissions for: ${configPath}`);
+} 

package/#Tools/claude-talk-to-figma-mcp/scripts/setup.sh

@@ -0,0 +1,30 @@
+#!/bin/bash
+
+# Detect package manager
+if command -v bun &> /dev/null; then
+    PACKAGE_MANAGER="bun"
+    echo "Bun detected, using it for setup..."
+else
+    PACKAGE_MANAGER="npm"
+    echo "Bun not found, using npm instead..."
+fi
+
+# Install dependencies
+echo "Installing dependencies..."
+if [ "$PACKAGE_MANAGER" = "bun" ]; then
+    bun install
+else
+    npm install
+fi
+
+# Configure for Claude Desktop
+echo "Configuring for Claude Desktop..."
+node scripts/configure-claude.js
+
+echo "Configuration completed."
+echo "To use the MCP, make sure to start the WebSocket server:"
+if [ "$PACKAGE_MANAGER" = "bun" ]; then
+    echo "bun socket"
+else
+    echo "npm run socket"
+fi