devskill 2.0.6 → 2.0.8

package/skills/penpot-uiux-design/references/platform-guidelines.md

@@ -0,0 +1,367 @@
+# Platform Design Guidelines Reference
+
+## Mobile Design Fundamentals
+
+### Screen Sizes
+
+| Device | Size | Design At |
+| ------ | ---- | --------- |
+| iPhone SE | 375×667 | Small mobile |
+| iPhone 14/15 | 390×844 | Standard mobile |
+| iPhone 14 Pro Max | 430×932 | Large mobile |
+| Android small | 360×640 | Minimum target |
+| Android large | 412×915 | Large Android |
+
+### Safe Areas
+
+```text
+┌─────────────────────────────────┐
+│ ▓▓▓▓▓▓▓ Status Bar ▓▓▓▓▓▓▓▓▓▓ │ 44-47px
+├─────────────────────────────────┤
+│                                 │
+│      Safe Content Area          │
+│                                 │
+│                                 │
+├─────────────────────────────────┤
+│ ▓▓▓▓▓▓ Home Indicator ▓▓▓▓▓▓▓ │ 34px
+└─────────────────────────────────┘
+
+```
+
+### Touch Targets
+
+- **Minimum:** 44×44pt (iOS) / 48×48dp (Android)
+- **Recommended:** 48×48px for all platforms
+- **Spacing:** Minimum 8px between targets
+
+---
+
+## iOS Human Interface Guidelines (HIG)
+
+### Design Philosophy
+
+- **Clarity:** Text is legible, icons precise, adornments subtle
+- **Deference:** UI helps people understand content, never competes
+- **Depth:** Distinct visual layers convey hierarchy
+
+### Navigation Patterns
+
+| Pattern | When to Use |
+| ------- | ----------- |
+| Tab Bar | 3-5 top-level destinations |
+| Navigation Bar | Hierarchical content |
+| Sidebar | iPad, rich content apps |
+| Search | Content discovery |
+
+### Tab Bar Specifications
+
+```text
+┌─────────────────────────────────┐
+│  🏠    🔍    ➕    💬    👤    │
+│ Home  Search Add  Chat  Profile │ 49pt height
+└─────────────────────────────────┘
+
+```
+
+- Max 5 tabs
+- Icons 25×25pt with 10pt labels
+- Active tab uses fill/tint color
+- Inactive tabs use gray
+
+### Navigation Bar
+
+```text
+┌─────────────────────────────────┐
+│ ‹ Back    Page Title    Action │ 44pt minimum
+└─────────────────────────────────┘
+
+```
+
+- Left: Back button or cancel
+- Center: Title
+- Right: Primary action (text or icon)
+
+### Typography (SF Pro)
+
+| Style | Size | Weight |
+| ----- | ---- | ------ |
+| Large Title | 34pt | Bold |
+| Title 1 | 28pt | Bold |
+| Title 2 | 22pt | Bold |
+| Title 3 | 20pt | Semibold |
+| Headline | 17pt | Semibold |
+| Body | 17pt | Regular |
+| Callout | 16pt | Regular |
+| Subhead | 15pt | Regular |
+| Footnote | 13pt | Regular |
+| Caption | 12pt | Regular |
+
+### iOS Colors (System)
+
+| Color | Light | Dark |
+| ----- | ----- | ---- |
+| Label | #000000 | #FFFFFF |
+| Secondary Label | #3C3C43 @ 60% | #EBEBF5 @ 60% |
+| Tertiary Label | #3C3C43 @ 30% | #EBEBF5 @ 30% |
+| System Blue | #007AFF | #0A84FF |
+| System Green | #34C759 | #30D158 |
+| System Red | #FF3B30 | #FF453A |
+| System Orange | #FF9500 | #FF9F0A |
+
+### iOS-Specific Patterns
+
+- **Swipe gestures:** Delete, archive, actions
+- **Pull to refresh:** Standard list refresh
+- **Long press:** Context menus
+- **Haptic feedback:** Confirm actions
+- **Edge swipe:** Back navigation
+
+---
+
+## Android Material Design
+
+### Android Design Philosophy
+
+- **Material as metaphor:** Physical properties, elevation
+- **Bold, graphic, intentional:** Deliberate color, typography, space
+- **Motion provides meaning:** Feedback and continuity
+
+### Android Navigation Patterns
+
+| Pattern | When to Use |
+| ------- | ----------- |
+| Bottom Navigation | 3-5 top destinations |
+| Navigation Drawer | 5+ destinations, less frequent |
+| Navigation Rail | Tablet landscape |
+| Tabs | Related content groups |
+
+### Bottom Navigation
+
+```text
+┌─────────────────────────────────┐
+│  🏠    🔍    📷    💬    👤    │
+│ Home  Search Camera Chat Account│ 80dp height
+└─────────────────────────────────┘
+
+```
+
+- 3-5 destinations
+- Icons 24dp with 12sp labels
+- Active: filled icon + primary color
+- Inactive: outlined icon + on-surface
+
+### App Bar
+
+```text
+┌─────────────────────────────────┐
+│ ≡  App Title                🔍 │ 64dp height
+└─────────────────────────────────┘
+
+```
+
+- Left: Navigation icon (menu or back)
+- Center: Title (can be left-aligned)
+- Right: Action icons (max 3)
+
+### Floating Action Button (FAB)
+
+- **Size:** 56dp standard, 40dp mini
+- **Position:** Bottom right, 16dp from edges
+- **Purpose:** Primary action only
+- **Behavior:** Can hide on scroll
+
+### Typography (Roboto)
+
+| Style | Size | Weight | Tracking |
+| ----- | ---- | ------ | -------- |
+| Display Large | 57sp | Regular | -0.25 |
+| Display Medium | 45sp | Regular | 0 |
+| Display Small | 36sp | Regular | 0 |
+| Headline Large | 32sp | Regular | 0 |
+| Headline Medium | 28sp | Regular | 0 |
+| Headline Small | 24sp | Regular | 0 |
+| Title Large | 22sp | Regular | 0 |
+| Title Medium | 16sp | Medium | 0.15 |
+| Title Small | 14sp | Medium | 0.1 |
+| Body Large | 16sp | Regular | 0.5 |
+| Body Medium | 14sp | Regular | 0.25 |
+| Body Small | 12sp | Regular | 0.4 |
+| Label Large | 14sp | Medium | 0.1 |
+| Label Medium | 12sp | Medium | 0.5 |
+| Label Small | 11sp | Medium | 0.5 |
+
+### Material Colors
+
+| Role | Purpose |
+| ---- | ------- |
+| Primary | Main brand color |
+| On Primary | Text/icons on primary |
+| Primary Container | Filled buttons, active states |
+| Secondary | Less prominent components |
+| Tertiary | Contrast, balance |
+| Error | Error states |
+| Surface | Card backgrounds |
+| On Surface | Text on surfaces |
+| Outline | Borders, dividers |
+
+### Elevation (Shadows)
+
+| Level | Elevation | Use Case |
+| ----- | --------- | -------- |
+| 0 | 0dp | Flat surfaces |
+| 1 | 1dp | Cards, raised buttons |
+| 2 | 3dp | Elevated cards |
+| 3 | 6dp | FAB resting |
+| 4 | 8dp | Dialogs, pickers |
+| 5 | 12dp | FAB pressed |
+
+### Android-Specific Patterns
+
+- **Snackbar:** Brief feedback at bottom
+- **Bottom sheet:** Additional content/actions
+- **Chips:** Filter, input, choice, action
+- **Speed dial FAB:** Multiple related actions
+
+---
+
+## Responsive Web Design
+
+### Breakpoints
+
+| Name | Width | Typical Device |
+| ---- | ----- | -------------- |
+| xs | <576px | Mobile portrait |
+| sm | 576-767px | Mobile landscape |
+| md | 768-991px | Tablet |
+| lg | 992-1199px | Small desktop |
+| xl | 1200-1399px | Desktop |
+| xxl | ≥1400px | Large desktop |
+
+### Grid System
+
+- **Columns:** 12-column grid standard
+- **Gutters:** 16-24px between columns
+- **Margins:** 16px (mobile) to 64px (desktop)
+- **Max content width:** 1200-1440px
+
+### Responsive Typography
+
+```text
+Mobile (base):
+  Body: 16px
+  H1: 28-32px
+  H2: 22-24px
+  
+Tablet:
+  Body: 16px
+  H1: 32-40px
+  H2: 24-28px
+  
+Desktop:
+  Body: 16-18px
+  H1: 40-56px
+  H2: 28-36px
+
+```
+
+### Mobile-First Approach
+
+1. Design for smallest screen first
+2. Add complexity for larger screens
+3. Content priority: What's essential?
+4. Performance: Minimize for mobile
+5. Touch-first interactions
+
+### Responsive Patterns
+
+| Pattern | Description |
+| ------- | ----------- |
+| Stack | Columns become rows on mobile |
+| Reflow | Content reorders based on priority |
+| Reveal | More content shown at larger sizes |
+| Off-canvas | Navigation slides in on mobile |
+| Scale | Elements scale proportionally |
+
+---
+
+## Desktop Applications
+
+### Window Chrome
+
+```text
+┌─────────────────────────────────────────┐
+│ ● ● ●   App Title              ─ □ ×  │ Title bar
+├────────┬────────────────────────────────┤
+│ Sidebar│ Content Area                   │
+│        │                                │
+│        │                                │
+│        │                                │
+│        ├────────────────────────────────┤
+│        │ Status Bar                     │
+└────────┴────────────────────────────────┘
+
+```
+
+### Keyboard-First Design
+
+- All actions accessible via keyboard
+- Visible keyboard shortcuts
+- Focus management for tab order
+- Search/command palette (Cmd/Ctrl+K)
+
+### Hover States
+
+Desktop has hover (mobile doesn't):
+
+- Show additional info on hover
+- Preview actions before click
+- Tooltips for icon-only buttons
+- Dropdown menus on hover
+
+### Dense Information
+
+Desktop allows for:
+
+- Smaller touch targets (32px min)
+- More visible information
+- Complex tables and data grids
+- Multi-column layouts
+- Side-by-side comparisons
+
+---
+
+## Cross-Platform Considerations
+
+### Shared Principles
+
+- Consistent brand identity
+- Same core user flows
+- Synchronized data/state
+- Familiar information architecture
+
+### Platform-Specific Adaptations
+
+| Aspect | iOS | Android | Web |
+| ------ | --- | ------- | --- |
+| Back | Left nav | Left or gesture | Browser back |
+| Primary action | Right nav | FAB | Top right button |
+| Lists | Swipe actions | Long press | Hover actions |
+| Menus | Action sheets | Bottom sheet | Dropdown/context |
+| Alerts | Centered modal | Centered modal | Various positions |
+
+### Design Tokens Across Platforms
+
+Create platform-agnostic tokens:
+
+```text
+// Spacing
+spacing-sm: 8
+spacing-md: 16
+spacing-lg: 24
+
+// These map to platform units
+iOS: points (pt)
+Android: density-independent pixels (dp)
+Web: pixels (px) or rem
+
+```

package/skills/penpot-uiux-design/references/setup-troubleshooting.md

@@ -0,0 +1,328 @@
+# Penpot MCP Server Setup & Troubleshooting
+
+Complete guide for installing, configuring, and troubleshooting the Penpot MCP Server.
+
+## Architecture Overview
+
+The Penpot MCP integration requires **three components** working together:
+
+```
+┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+│   MCP Client    │────▶│   MCP Server    │◀───▶│  Penpot Plugin  │
+│ (VS Code/Claude)│     │  (port 4401)    │     │ (in browser)    │
+└─────────────────┘     └────────┬────────┘     └────────┬────────┘
+                                 │                       │
+                                 │    WebSocket          │
+                                 │    (port 4402)        │
+                                 └───────────────────────┘
+```
+
+1. **MCP Server** - Exposes tools to your AI client (HTTP on port 4401)
+2. **Plugin Server** - Serves the Penpot plugin files (HTTP on port 4400)
+3. **Penpot MCP Plugin** - Runs inside Penpot browser, executes design commands
+
+## Prerequisites
+
+- **Node.js v22+** - [Download](https://nodejs.org/)
+- **Git** - For cloning the repository
+- **Modern browser** - Chrome, Firefox, or Chromium-based browser
+
+Verify Node.js installation:
+```bash
+node --version  # Should be v22.x or higher
+npm --version
+npx --version
+```
+
+## Installation
+
+### Step 1: Clone and Install
+
+```bash
+# Clone the repository
+git clone https://github.com/penpot/penpot-mcp.git
+cd penpot-mcp
+
+# Install dependencies
+npm install
+```
+
+### Step 2: Build and Start Servers
+
+```bash
+# Build all components and start servers
+npm run bootstrap
+```
+
+This command:
+
+- Installs dependencies for all components
+- Builds the MCP server and plugin
+- Starts both servers (MCP on 4401, Plugin on 4400)
+
+**Expected output:**
+
+```txt
+MCP Server listening on http://localhost:4401
+Plugin server listening on http://localhost:4400
+WebSocket server listening on port 4402
+```
+
+### Step 3: Load Plugin in Penpot
+
+1. Open [Penpot](https://design.penpot.app/) in your browser
+2. Open or create a design file
+3. Go to **Plugins** menu (or press the plugins icon)
+4. Click **Load plugin from URL**
+5. Enter: `http://localhost:4400/manifest.json`
+6. The plugin UI will appear - click **"Connect to MCP server"**
+7. Status should change to **"Connected to MCP server"**
+
+> **Important**: Keep the plugin UI open while using MCP tools. Closing it disconnects the server.
+
+### Step 4: Configure Your MCP Client
+
+#### VS Code with GitHub Copilot
+
+Add to your VS Code `settings.json`:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "penpot": {
+        "url": "http://localhost:4401/sse"
+      }
+    }
+  }
+}
+```
+
+Or use the HTTP endpoint:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "penpot": {
+        "url": "http://localhost:4401/mcp"
+      }
+    }
+  }
+}
+```
+
+#### Claude Desktop
+
+Claude Desktop requires the `mcp-remote` proxy (stdio-only transport):
+
+1. Install the proxy:
+
+   ```bash
+   npm install -g mcp-remote
+   ```
+
+2. Edit Claude Desktop config:
+   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+   - **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
+   - **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+3. Add the Penpot server:
+
+   ```json
+   {
+     "mcpServers": {
+       "penpot": {
+         "command": "npx",
+         "args": ["-y", "mcp-remote", "http://localhost:4401/sse", "--allow-http"]
+       }
+     }
+   }
+   ```
+
+4. **Fully quit** Claude Desktop (File → Quit, not just close window) and restart
+
+#### Claude Code (CLI)
+
+```bash
+claude mcp add penpot -t http http://localhost:4401/mcp
+```
+
+## Troubleshooting
+
+### Connection Issues
+
+#### "Plugin cannot connect to MCP server"
+
+**Symptoms**: Plugin shows "Not connected" even after clicking Connect
+
+**Solutions**:
+
+1. Verify servers are running:
+   ```bash
+   # Check if ports are in use
+   lsof -i :4401  # MCP server
+   lsof -i :4402  # WebSocket
+   lsof -i :4400  # Plugin server
+   ```
+
+2. Restart the servers:
+
+   ```bash
+   # In the penpot-mcp directory
+   npm run start:all
+   ```
+
+3. Check browser console (F12) for WebSocket errors
+
+#### Browser Blocks Local Connection
+
+**Symptoms**: Browser refuses to connect to localhost from Penpot
+
+**Cause**: Chromium 142+ enforces Private Network Access (PNA) restrictions
+
+**Solutions**:
+
+1. **Chrome/Chromium**: When prompted, allow access to local network
+2. **Brave**: Disable Shield for the Penpot website:
+   - Click the Brave Shield icon in address bar
+   - Toggle Shield off for this site
+3. **Try Firefox**: Firefox doesn't enforce these restrictions as strictly
+
+#### "WebSocket connection failed"
+
+**Solutions**:
+
+1. Check firewall settings - allow ports 4400, 4401, 4402
+2. Disable VPN if active
+3. Check for conflicting applications using the same ports
+
+### MCP Client Issues
+
+#### Tools Not Appearing in VS Code/Claude
+
+1. **Verify endpoint**:
+
+   ```bash
+   # Test the SSE endpoint
+   curl http://localhost:4401/sse
+   
+   # Test the MCP endpoint
+   curl http://localhost:4401/mcp
+   ```
+
+2. **Check configuration syntax** - JSON must be valid
+3. **Restart the MCP client** completely
+4. **Check MCP server logs**:
+
+   ```bash
+   # Logs are in mcp-server/logs/
+   tail -f mcp-server/logs/mcp-server.log
+   ```
+
+#### "Tool execution timed out"
+
+**Cause**: Plugin disconnected or operation took too long
+
+**Solutions**:
+
+1. Ensure plugin UI is still open in Penpot
+2. Verify plugin shows "Connected" status
+3. Try reconnecting: click Disconnect then Connect in plugin
+
+### Plugin Issues
+
+#### "Plugin failed to load"
+
+1. Verify plugin server is running on port 4400
+2. Try accessing `http://localhost:4400/manifest.json` directly in browser
+3. Clear browser cache and reload Penpot
+4. Remove and re-add the plugin
+
+#### "Cannot find penpot object"
+
+**Cause**: Plugin not properly initialized or design file not open
+
+**Solutions**:
+
+1. Make sure you have a design file open (not just the dashboard)
+2. Wait a few seconds after opening file before connecting
+3. Refresh Penpot and reload the plugin
+
+### Server Issues
+
+#### Port Already in Use
+
+```bash
+# Find process using the port
+lsof -i :4401
+
+# Kill the process if needed
+kill -9 <PID>
+```
+
+Or configure different ports via environment variables:
+```bash
+PENPOT_MCP_SERVER_PORT=4501 npm run start:all
+```
+
+#### Server Crashes on Startup
+
+1. Check Node.js version (must be v22+)
+2. Delete `node_modules` and reinstall:
+
+   ```bash
+   rm -rf node_modules
+   npm install
+   npm run bootstrap
+   ```
+
+## Configuration Reference
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PENPOT_MCP_SERVER_PORT` | 4401 | HTTP/SSE server port |
+| `PENPOT_MCP_WEBSOCKET_PORT` | 4402 | WebSocket server port |
+| `PENPOT_MCP_SERVER_LISTEN_ADDRESS` | localhost | Server bind address |
+| `PENPOT_MCP_LOG_LEVEL` | info | Log level (trace/debug/info/warn/error) |
+| `PENPOT_MCP_LOG_DIR` | logs | Log file directory |
+| `PENPOT_MCP_REMOTE_MODE` | false | Enable remote mode (disables file system access) |
+
+### Example: Custom Configuration
+
+```bash
+# Run on different ports with debug logging
+PENPOT_MCP_SERVER_PORT=5000 \
+PENPOT_MCP_WEBSOCKET_PORT=5001 \
+PENPOT_MCP_LOG_LEVEL=debug \
+npm run start:all
+```
+
+## Verifying the Setup
+
+Run this checklist to confirm everything works:
+
+1. **Servers Running**:
+   ```bash
+   curl -s http://localhost:4401/sse | head -1
+   # Should return SSE stream headers
+   ```
+
+2. **Plugin Connected**: Plugin UI shows "Connected to MCP server"
+
+3. **Tools Available**: In your MCP client, verify these tools appear:
+   - `mcp__penpot__execute_code`
+   - `mcp__penpot__export_shape`
+   - `mcp__penpot__import_image`
+   - `mcp__penpot__penpot_api_info`
+
+4. **Test Execution**: Ask your AI assistant to run a simple command:
+   > "Use Penpot to get the current page name"
+
+## Getting Help
+
+- **GitHub Issues**: [penpot/penpot-mcp/issues](https://github.com/penpot/penpot-mcp/issues)
+- **GitHub Discussions**: [penpot/penpot-mcp/discussions](https://github.com/penpot/penpot-mcp/discussions)
+- **Penpot Community**: [community.penpot.app](https://community.penpot.app/)

package/skills/php-mcp-server-generator/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright GitHub, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.