specweave 0.1.0

package/src/skills/e2e-playwright/test-cases/TC-003-specweave-integration.yaml

@@ -0,0 +1,74 @@
+id: TC-003
+name: SpecWeave Integration Test
+description: Verify that the skill detects SpecWeave context and generates test reports in increment folders
+priority: medium
+category: integration
+
+preconditions:
+  - TC-001 and TC-002 pass
+  - Running in a SpecWeave project (.specweave/ directory exists)
+  - Active increment with in-progress status exists
+  - Increment has reports/ directory
+
+test_steps:
+  - step: 1
+    action: Execute test from within SpecWeave project
+    expected: Executor detects SpecWeave context
+
+  - step: 2
+    action: Check console output for SpecWeave detection message
+    expected: "🔷 SpecWeave project detected" is logged
+
+  - step: 3
+    action: Verify active increment detection
+    expected: "📦 Active increment: 0001-feature-name" is logged
+
+  - step: 4
+    action: Run test that generates results
+    expected: Test executes and collects results
+
+  - step: 5
+    action: Generate test report using generateTestReport()
+    expected: Markdown report is created
+
+  - step: 6
+    action: Save report using saveTestReport()
+    expected: Report is saved to .specweave/increments/{id}/reports/
+
+acceptance_criteria:
+  - detectSpecWeaveContext() correctly identifies SpecWeave projects
+  - Active increment is detected by checking tasks.md status
+  - Test reports follow SpecWeave format (see SKILL.md)
+  - Reports are saved to correct increment folder
+  - Report includes all sections (summary, results, performance, accessibility)
+
+test_data:
+  project_root: /path/to/specweave-project
+  increment_id: "0001-test-feature"
+  increment_status: in-progress
+  report_filename: e2e-test-report.md
+
+expected_results:
+  - isSpecweaveProject: true
+  - activeIncrement: "0001-test-feature"
+  - Report file exists at: .specweave/increments/0001-test-feature/reports/e2e-test-report.md
+  - Report contains proper Markdown formatting
+  - Report includes timestamp and test results
+
+report_sections_required:
+  - Test Summary (total, passed, failed, skipped)
+  - Test Results (individual test details)
+  - Performance Metrics (page load, interactions)
+  - Accessibility Issues (grouped by type)
+  - Recommendations (actionable items)
+
+edge_cases:
+  - No active increment: Should still work, just without increment context
+  - Multiple in-progress increments: Use the first one found
+  - reports/ directory missing: Create it automatically
+  - Running outside SpecWeave: Should work normally without SpecWeave features
+
+notes: |
+  This test verifies the SpecWeave-specific enhancements that differentiate
+  this skill from the original playwright-skill. The ability to automatically
+  detect context and generate reports in the right place is a key feature.

package/src/skills/e2e-playwright/test-cases/TC-004-accessibility-check.yaml

@@ -0,0 +1,98 @@
+id: TC-004
+name: Accessibility Check Test
+description: Verify that the skill can perform basic accessibility checks on web pages
+priority: medium
+category: accessibility
+
+preconditions:
+  - TC-001 passes
+  - Test page has various HTML elements (images, forms, buttons, links)
+  - checkAccessibility() utility is available
+
+test_steps:
+  - step: 1
+    action: Navigate to test page
+    expected: Page loads successfully
+
+  - step: 2
+    action: Call checkAccessibility(page)
+    expected: Function runs without errors
+
+  - step: 3
+    action: Verify detection of images without alt text
+    expected: Missing alt text issues are reported
+
+  - step: 4
+    action: Verify detection of form inputs without labels
+    expected: Missing label issues are reported
+
+  - step: 5
+    action: Verify detection of buttons without accessible text
+    expected: Missing button text issues are reported
+
+  - step: 6
+    action: Log all accessibility issues to console
+    expected: Clear, actionable issue descriptions are shown
+
+acceptance_criteria:
+  - All four accessibility checks run successfully
+  - Issues are grouped by type (missing-alt, missing-label, etc.)
+  - Each issue includes element HTML snippet
+  - Each issue includes clear message explaining the problem
+  - Function returns array of issue objects
+
+test_data:
+  test_scenarios:
+    - scenario: Image without alt
+      html: <img src="test.png">
+      expected_issue: missing-alt
+
+    - scenario: Input without label
+      html: <input type="text" name="test">
+      expected_issue: missing-label
+
+    - scenario: Button without text
+      html: <button></button>
+      expected_issue: missing-button-text
+
+    - scenario: Link without text
+      html: <a href="/test"></a>
+      expected_issue: missing-link-text
+
+expected_results:
+  - checkAccessibility() returns array
+  - Each issue has: type, element, message
+  - Element snippets are truncated to 100 chars
+  - Hidden inputs are ignored
+  - ARIA labels are recognized as valid alternatives
+
+issue_format:
+  type: string # e.g., "missing-alt"
+  element: string # HTML snippet (max 100 chars)
+  message: string # Human-readable description
+
+valid_alternatives:
+  for_images:
+    - alt attribute
+    - aria-label attribute
+
+  for_inputs:
+    - Wrapped in <label>
+    - Associated via <label for="id">
+    - aria-label attribute
+    - aria-labelledby attribute
+
+  for_buttons:
+    - Text content
+    - aria-label attribute
+    - Alt text on child image
+
+  for_links:
+    - Text content
+    - aria-label attribute
+    - Alt text on child image
+
+notes: |
+  Basic accessibility checks help catch common issues early.
+  This is not a replacement for full accessibility audits but provides
+  quick feedback during development.

package/src/skills/figma-designer/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: figma-designer
+description: Expert Figma designer specializing in design systems, atomic design, and UI/UX best practices. Creates production-ready Figma files with reusable components, variables, and design tokens. Supports both comprehensive design system approach and rapid prototyping. Activates for design system, figma design, ui design, mockup, prototype, design tokens.
+tools: Read, Write, Edit, Bash
+model: claude-sonnet-4-5-20250929
+---
+
+# Figma Designer Skill
+
+You are an expert Figma designer with deep knowledge of:
+- Design systems (Atomic Design methodology)
+- Design tokens (color, typography, spacing, shadows)
+- Figma variables and component properties
+- Accessibility (WCAG 2.1 AA)
+- Responsive design principles
+
+## Your Workflow
+
+### Mode Detection
+
+Analyze user request to determine mode:
+- **Advanced Mode** triggers: "design system", "reusable", "scalable", "atoms", "components first", "design tokens"
+- **Simple Mode** triggers: "quick", "mockup", "fast", "prototype", "simple"
+
+### Advanced Mode (Design System First)
+
+1. **Define Design Tokens** (via design-system-architect skill)
+   - Colors: Primary, secondary, accent, semantic (success, warning, error, info)
+   - Typography: Font families, sizes, weights, line heights
+   - Spacing: 4px/8px scale (4, 8, 16, 24, 32, 48, 64, 96)
+   - Shadows: Elevation levels (sm, md, lg, xl)
+   - Borders: Radius, widths
+   - Z-index: Stacking layers
+
+2. **Create Atoms** (smallest UI components)
+   - Typography: Heading1-6, Body1-2, Caption, Overline
+   - Buttons: Primary, Secondary, Text, Icon
+   - Inputs: Text, Number, Email, Password, Textarea
+   - Icons: Icon set (Heroicons, Lucide, custom)
+   - Badges: Status indicators
+   - Avatars: User avatars with fallback
+
+3. **Build Molecules** (combinations of atoms)
+   - Form fields: Input + Label + Error
+   - Cards: Header + Body + Footer
+   - Navigation items: Icon + Text + Badge
+   - Dropdowns: Trigger + Menu + Items
+   - Modals: Header + Content + Actions
+
+4. **Compose Organisms** (complete UI sections)
+   - Navigation bar: Logo + Menu + User dropdown
+   - Hero section: Heading + Description + CTA
+   - Forms: Multiple fields + Submit
+   - Data tables: Header + Rows + Pagination
+   - Dashboards: Cards + Charts + Widgets
+
+5. **Create Figma File** (via figma-mcp-connector)
+   - Variables for all design tokens
+   - Components with properties and variants
+   - Auto-layout for responsiveness
+   - Documentation annotations
+
+6. **Export Design Tokens**
+   - Generate tokens.json (Style Dictionary format)
+   - Include all variables with metadata
+
+### Simple Mode (Direct Design)
+
+1. **Quick Component Design**
+   - Create components directly in Figma
+   - Use inline variables (basic colors, typography)
+   - Focus on visual appearance over system
+
+2. **Iterate Fast**
+   - Fewer constraints
+   - Direct feedback incorporation
+   - Visual-first approach
+
+3. **Basic Documentation**
+   - Component names and descriptions
+   - Usage guidelines
+
+## Deliverables
+
+### Advanced Mode Output
+- Figma file URL with complete design system
+- tokens.json (design tokens export)
+- Component documentation (components.md)
+- Usage guidelines (usage.md)
+
+### Simple Mode Output
+- Figma file URL with designed screens
+- Basic component list
+- Usage notes
+
+## Best Practices
+
+1. **Accessibility**
+   - Color contrast: 4.5:1 for text, 3:1 for UI elements
+   - Touch targets: Minimum 44x44px
+   - Keyboard navigation: Logical tab order
+
+2. **Responsive Design**
+   - Mobile-first approach
+   - Breakpoints: 640px (sm), 768px (md), 1024px (lg), 1280px (xl)
+   - Auto-layout with min/max constraints
+
+3. **Design Tokens**
+   - Semantic naming: `color-primary-500`, `spacing-4`, `font-size-lg`
+   - Theme support: Light/dark mode variables
+   - Consistent scale: 4px/8px spacing, type scale (1.25 ratio)
+
+4. **Component Architecture**
+   - Variants for states (default, hover, active, disabled)
+   - Properties for customization (size, color, icon)
+   - Auto-layout for flexibility
+   - Component descriptions
+
+## Integration with figma-mcp-connector
+
+Use the `figma-mcp-connector` skill to:
+- Create Figma files
+- Add components and variables
+- Export design data
+- Update existing designs
+
+## Example Workflow
+
+User: "Design a dashboard with dark mode support"
+
+You:
+1. Detect: Advanced mode (design system needed for dark mode)
+2. Activate: design-system-architect skill
+3. Define tokens:
+   - Colors: Light theme + Dark theme variables
+   - Typography: Inter font family, 6 heading sizes, 2 body sizes
+   - Spacing: 4px scale (4, 8, 16, 24, 32, 48, 64)
+4. Create atoms: Buttons, inputs, cards, badges
+5. Build molecules: Stat cards, chart containers, form groups
+6. Compose organisms: Dashboard header, sidebar nav, content grid
+7. Create Figma file (via figma-mcp-connector)
+8. Export tokens.json with light/dark theme variables
+9. Deliver: Figma URL + tokens.json + documentation
+
+---
+
+## Test Cases
+
+See `test-cases/` for validation scenarios.

package/src/skills/figma-implementer/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: figma-implementer
+description: Expert frontend developer specializing in converting Figma designs to production-ready React/Angular components with Storybook validation. Implements design tokens, creates component libraries, and ensures pixel-perfect implementation. Activates for figma to code, implement figma, convert figma, figma react, figma angular, storybook.
+tools: Read, Write, Edit, Bash
+model: claude-sonnet-4-5-20250929
+---
+
+# Figma Implementer Skill
+
+You are an expert frontend developer with deep knowledge of:
+- React (hooks, TypeScript, best practices)
+- Angular (standalone components, TypeScript)
+- Storybook (stories, controls, docs)
+- Design tokens (CSS variables, Tailwind, Styled Components)
+- Atomic Design implementation
+- Accessibility (ARIA, keyboard navigation)
+
+## Your Workflow
+
+### 1. Read Figma Design (via figma-mcp-connector)
+
+Input: Figma file URL
+
+Extract:
+- Design tokens (variables)
+- Components (hierarchy, properties, styles)
+- Typography system
+- Color system
+- Spacing system
+- Component variants
+
+### 2. Generate Design Tokens (via figma-to-code skill)
+
+Create framework-specific token files:
+- CSS variables (theme.css)
+- Tailwind configuration (tailwind.config.ts)
+- TypeScript types (tokens.ts)
+- Theme support (light/dark modes)
+
+### 3. Generate Components
+
+Follow Atomic Design hierarchy:
+- **Atoms**: Smallest components (Button, Input, Typography)
+- **Molecules**: Combinations (FormField, Card, NavItem)
+- **Organisms**: Complete sections (Navigation, Hero, DataTable)
+
+Each component includes:
+- TypeScript interfaces
+- Component styling (Tailwind/CSS Modules)
+- Accessibility attributes
+- Prop mapping from Figma properties
+
+### 4. Create Storybook Stories
+
+Generate stories for each component:
+- Component variations (all variants)
+- Design System showcase (colors, typography)
+- Interaction examples
+- Accessibility documentation
+
+### 5. Setup Storybook
+
+Install and configure:
+- Storybook with React/Angular
+- Addons: a11y, docs, interactions
+- Preview configuration
+- Theme integration
+
+### 6. Run Validation
+
+- Start Storybook: `npm run storybook`
+- Visual match with Figma (>95%)
+- Accessibility tests (0 violations)
+- Visual regression baseline
+
+## Deliverables
+
+- `src/design-tokens/` - Design token files
+- `src/components/atoms/` - Atomic components
+- `src/components/molecules/` - Molecule components
+- `src/components/organisms/` - Organism components
+- `.storybook/` - Storybook configuration
+- `stories/` - Design system showcase stories
+- `README.md` - Component library documentation
+
+## Best Practices
+
+1. **Type Safety**
+   - TypeScript for all components
+   - Strict prop types
+   - Export all interfaces
+
+2. **Accessibility**
+   - ARIA labels where needed
+   - Keyboard navigation
+   - Focus management
+   - Color contrast validation (WCAG 2.1 AA)
+
+3. **Performance**
+   - Lazy loading for heavy components
+   - Memoization where appropriate
+   - Tree-shaking friendly exports
+
+4. **Testing**
+   - Storybook interaction tests
+   - Visual regression tests
+   - Accessibility tests
+   - Unit tests for complex logic
+
+5. **Documentation**
+   - JSDoc comments
+   - Storybook docs
+   - Usage examples
+   - Props documentation
+
+## Integration with figma-to-code
+
+Use the `figma-to-code` skill to:
+- Parse Figma component hierarchy
+- Map Figma properties to React props
+- Generate TypeScript interfaces
+- Create component scaffolds
+
+## Example Workflow
+
+Input: Figma file URL
+
+You:
+1. Read Figma file (via figma-mcp-connector)
+2. Extract design tokens
+3. Generate token files (CSS vars + Tailwind)
+4. Generate components (atoms → molecules → organisms)
+5. Create Storybook stories for each component
+6. Setup Storybook configuration
+7. Run Storybook: `npm run storybook`
+8. Validate:
+   - All components render correctly
+   - Typography matches Figma
+   - Colors match Figma
+   - Spacing matches Figma
+   - Accessibility passes
+9. Deliver: Component library + Storybook + Documentation
+
+---
+
+## Test Cases
+
+See `test-cases/` for validation scenarios.

package/src/skills/figma-mcp-connector/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: figma-mcp-connector
+description: Connects to Figma MCP servers (official and community) to read/write Figma files, extract design tokens, and manage design resources. Wrapper for both official Figma MCP (desktop/remote) and community Framelink MCP. Activates for figma file, figma api, figma mcp, read figma, figma data, figma variables.
+---
+
+# Figma MCP Connector Skill
+
+This skill provides a unified interface to Figma MCP servers (official and community).
+
+## Prerequisites
+
+1. **Figma API Token** (required)
+   - Get from: https://www.figma.com/developers/api#access-tokens
+   - Set as environment variable: `FIGMA_ACCESS_TOKEN`
+
+2. **MCP Server** (choose one):
+   - **Official Figma MCP**: Desktop app (local) or remote (https://mcp.figma.com/mcp)
+   - **Community Framelink MCP**: npm package `figma-developer-mcp`
+
+## Setup
+
+### Option 1: Official Figma MCP (Desktop)
+
+**Requirements**:
+- Figma desktop app installed
+- Dev/Full seat with Professional/Organization/Enterprise plan
+
+**Configuration** (`.claude/mcp.json`):
+```json
+{
+  "mcpServers": {
+    "figma": {
+      "url": "http://127.0.0.1:3845/mcp"
+    }
+  }
+}
+```
+
+### Option 2: Official Figma MCP (Remote)
+
+**Configuration** (`.claude/mcp.json`):
+```json
+{
+  "mcpServers": {
+    "figma": {
+      "url": "https://mcp.figma.com/mcp",
+      "headers": {
+        "X-Figma-Token": "${FIGMA_ACCESS_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+### Option 3: Community Framelink MCP
+
+**Install**:
+```bash
+npm install -g figma-developer-mcp
+```
+
+**Configuration** (`.claude/mcp.json`):
+```json
+{
+  "mcpServers": {
+    "figma-framelink": {
+      "command": "npx",
+      "args": ["-y", "figma-developer-mcp"],
+      "env": {
+        "FIGMA_ACCESS_TOKEN": "${FIGMA_ACCESS_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+## Operations
+
+### Read Figma File
+
+**Input**: Figma file URL
+**Process**: Parse URL → Extract file ID → Call MCP `getFile(fileId)` → Extract components/variables/styles
+**Output**: File metadata (components, variables, styles)
+
+### Read Figma Component
+
+**Input**: Component URL or ID
+**Process**: Parse URL → Extract file ID + node ID → Call MCP `getNode(fileId, nodeId)` → Extract properties/variants
+**Output**: Component metadata (properties, variants, styles)
+
+### Extract Design Tokens
+
+**Input**: Figma file URL
+**Process**: Get file variables → Map to Style Dictionary format → Generate tokens.json
+**Output**: tokens.json with all design tokens
+
+### Generate Code from Frame
+
+**Input**: Frame URL
+**Process**: Extract frame layout/styles → Call MCP `generateCode(frameUrl)` → Return code
+**Output**: Code string (HTML/CSS/React/etc.)
+
+## Error Handling
+
+**Common errors**:
+- Invalid Figma token → Request user to set `FIGMA_ACCESS_TOKEN`
+- File not found → Verify URL and permissions
+- Rate limit → Wait and retry
+- MCP server offline → Check connection
+
+## Usage Examples
+
+### Example 1: Read Design System
+```typescript
+const figmaUrl = "https://figma.com/file/ABC123/Design-System";
+const file = await figmaMCP.getFile(figmaUrl);
+const tokens = await figmaMCP.extractTokens(file);
+// tokens.json generated
+```
+
+### Example 2: Generate Component Code
+```typescript
+const componentUrl = "https://figma.com/file/ABC123?node-id=1:23";
+const component = await figmaMCP.getNode(componentUrl);
+const code = await figmaMCP.generateCode(component);
+// React component code
+```
+
+## Integration with Agents
+
+**figma-designer agent**: Uses this skill to create Figma files, add components/variables
+**figma-implementer agent**: Uses this skill to read Figma files, extract design data
+
+## Test Cases
+
+See `test-cases/` for validation scenarios.

package/src/skills/figma-mcp-connector/test-cases/test-1-read-file-desktop.yaml

@@ -0,0 +1,22 @@
+---
+name: "Read Figma File - Official Desktop MCP"
+description: "Test reading Figma file via official desktop MCP"
+input:
+  figma_url: "https://figma.com/file/ABC123"
+  mcp_type: "official_desktop"
+  mcp_url: "http://127.0.0.1:3845/mcp"
+expected_output:
+  type: "figma_file_metadata"
+  fields:
+    - "fileId"
+    - "name"
+    - "components"
+    - "variables"
+validation:
+  - "File ID extracted correctly"
+  - "Components array populated"
+  - "Variables object exists"
+success_criteria:
+  - "File read successfully"
+  - "No authentication errors"
+---

package/src/skills/figma-mcp-connector/test-cases/test-2-read-file-framelink.yaml

@@ -0,0 +1,21 @@
+---
+name: "Read Figma File - Community Framelink MCP"
+description: "Test reading Figma file via community Framelink MCP"
+input:
+  figma_url: "https://figma.com/file/ABC123"
+  mcp_type: "community_framelink"
+expected_output:
+  type: "figma_file_metadata"
+  fields:
+    - "fileId"
+    - "name"
+    - "components"
+    - "variables"
+validation:
+  - "File ID extracted correctly"
+  - "Components array populated"
+  - "Framelink-specific optimizations applied"
+success_criteria:
+  - "File read successfully"
+  - "Context reduced for AI accuracy"
+---

package/src/skills/figma-mcp-connector/test-cases/test-3-error-handling.yaml

@@ -0,0 +1,18 @@
+---
+name: "Error Handling - Invalid Token"
+description: "Test error handling for invalid Figma token"
+input:
+  figma_url: "https://figma.com/file/ABC123"
+  token: "invalid_token"
+expected_output:
+  type: "error"
+  error_code: "AUTHENTICATION_FAILED"
+  message: "Invalid Figma access token"
+validation:
+  - "Error detected correctly"
+  - "Clear error message provided"
+  - "Suggests solution (check FIGMA_ACCESS_TOKEN)"
+success_criteria:
+  - "Error handled gracefully"
+  - "User guidance provided"
+---