feat(vibe-code): add mcp config and docs for design system usage (#423)

- adds Figma and Storybook mcps
- adds guidelines for developing front-end using design system
components (`ui-library`)

Author: jmikitova

.mcp.json

@@ -0,0 +1,12 @@
+{
+    "mcpServers": {
+        "storybook": {
+            "type": "http",
+            "url": "https://baldasseva--storybook-mcp.apify.actor/mcp?token=${APIFY_TOKEN}"
+        },
+        "figma": {
+            "type": "http",
+            "url": "https://mcp.figma.com/mcp"
+        }
+    }
+}

AGENTS.md

@@ -306,6 +306,22 @@ We use **4 spaces** for indentation (configured in `.editorconfig`).
 - **Don't** use `Promise.then()` - prefer `async/await`
 - **Don't** create tools without proper error handling and user-friendly messages
 
+
+### Design System Compliance (MANDATORY)
+
+**READ FIRST**: [DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md](DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md) - Complete design system rules
+
+**Quick Rules** (Zero tolerance):
+- ✅ ALWAYS use `theme.*` tokens (colors, spacing)
+- ❌ NEVER hardcode: `#hex`, `rgb()`, `Npx` values, font sizes
+- ✅ Import from `@apify/ui-library` only
+- ✅ Check `mcp__storybook__*` and `mcp__figma__*` availability before UI work
+- ✅ Call `mcp__storybook__get-ui-building-instructions` first
+- ✅ Read 1-3 similar components for patterns (max 3 files)
+- ✅ Verify zero hardcoded values before submitting
+
+**Figma Integration**: Call `mcp__figma__get_design_context` when working from designs.
+
 ### What NOT to do (beyond code)
 
 - Don't add features not in the requirements

DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md

@@ -0,0 +1,260 @@
+# Design System Agent Instructions
+
+**CRITICAL**: These instructions are MANDATORY for all UI/frontend work. Follow exactly as written.
+
+## Pre-Work Checklist
+
+Before ANY UI/component work:
+
+1. **Check MCP availability (recommended)**:
+   - Search for `mcp__storybook__*` tools
+   - Search for `mcp__figma__*` tools
+   - If available: Use them to get design context and component examples
+   - If missing: Continue with pattern discovery via code exploration
+
+2. **Load design context** (if MCPs available):
+   ```
+   Call: mcp__storybook__get-ui-building-instructions
+   Call: mcp__figma__get_design_context (if working from designs)
+   ```
+
+3. **Read existing patterns**:
+   - The Storybook MCP provides component examples and usage patterns
+   - Find similar widgets/components in the project: `src/web/src/**/*{keyword}*.{tsx,ts}`
+   - Use Grep to find token usage patterns: `theme\.color\.|theme\.space\.|theme\.radius\.`
+   - Read 1-2 similar components in the project to understand patterns
+   - DO NOT read more than 3 files for context
+
+## Strict Rules (Zero Tolerance)
+
+### 1. Design Tokens ONLY
+**NEVER** hardcode values. Use `theme.*` exclusively:
+
+```typescript
+// ❌ FORBIDDEN
+color: '#1976d2'
+padding: '8px'
+border-radius: '4px'
+font-size: '14px'
+
+// ✅ REQUIRED
+color: ${theme.color.primary.action}
+padding: ${theme.space.space8}
+border-radius: ${theme.radius.radius8}
+// For typography, prefer using <Text> or <Heading> components
+```
+
+**Token Reference** (understand the patterns):
+- Colors: `theme.color.{category}.{property}`
+  - Example categories: `neutral`, `primary`, `primaryBlack`, `success`, `warning`, `danger`
+  - Example properties: `text`, `textMuted`, `background`, `backgroundSubtle`, `action`, `actionHover`, `border`, `icon`, etc.
+- Spacing: `theme.space.space{N}`
+  - Examples: `space8`, `space16`, `space24` (incremental values available)
+- Radius: `theme.radius.radius{N}`
+  - Examples: `radius4`, `radius6`, `radius8`, `radius12`, `radiusFull`
+- Shadows: `theme.shadow.{name}`
+  - Examples: `shadow1`, `shadow2`, `shadow3`, `shadowActive`
+
+**To discover available tokens**: Use Storybook MCP or Grep existing usage in `src/web/src`
+
+### 2. Component Imports
+```typescript
+// ✅ Import from ui-library
+import { Button, Badge, Chip } from '@apify/ui-library';
+
+// ❌ NEVER create duplicate components
+// ❌ NEVER import from relative paths outside ui-library
+```
+
+### 3. Styled Components Pattern
+```typescript
+import styled from 'styled-components';
+import { theme } from '@apify/ui-library';
+
+// ✅ Correct pattern
+const StyledComponent = styled.div<{ $variant?: string }>`
+    color: ${theme.color.neutral.text};
+    padding: ${theme.space.space16};
+
+    ${({ $variant }) => $variant === 'primary' && css`
+        background: ${theme.color.primary.background};
+    `}
+`;
+
+// Note: Use $ prefix for transient props ($variant, $isActive, etc.)
+```
+
+### 4. Component Structure (Strict Order)
+```typescript
+// 1. Imports (grouped)
+import { forwardRef } from 'react';
+import styled from 'styled-components';
+import { theme } from '@apify/ui-library';
+
+// 2. Constants & Types
+export const COMPONENT_VARIANTS = { ... } as const;
+type ComponentVariants = ValueOf<typeof COMPONENT_VARIANTS>;
+
+// 3. Styled Components
+const StyledWrapper = styled.div`...`;
+
+// 4. Component Implementation
+export const Component = forwardRef<HTMLElement, Props>((props, ref) => {
+    // implementation
+});
+
+// 5. Display Name
+Component.displayName = 'Component';
+```
+
+### 5. Color Usage Rules
+
+**Semantic Naming Required**:
+- Text: `theme.color.{category}.text`, `.textMuted`, `.textSubtle`, `.textDisabled`
+- Backgrounds: `theme.color.{category}.background`, `.backgroundSubtle`, `.backgroundMuted`
+- Interactive: `theme.color.{category}.action`, `.actionHover`, `.actionActive`
+- Borders: `theme.color.{category}.border`, `.separatorSubtle`, `.fieldBorder`
+- Icons: `theme.color.{category}.icon`, `.iconSubtle`, `.iconDisabled`
+
+**State Variants**:
+```typescript
+// Default → Hover → Active states
+background: ${theme.color.primary.action};
+&:hover { background: ${theme.color.primary.actionHover}; }
+&:active { background: ${theme.color.primary.actionActive}; }
+```
+
+### 6. Spacing Rules
+- Gaps between elements: `space4`, `space8`, `space12`
+- Component padding: `space8`, `space12`, `space16`
+- Section margins: `space16`, `space24`, `space32`
+- Large layouts: `space40`, `space64`, `space80`
+
+**NEVER** use arbitrary values like `gap: 10px` - round to nearest token.
+
+### 7. Typography Rules
+```typescript
+// ✅ Use Text or Heading components from ui-library
+import { Text, Heading } from '@apify/ui-library';
+
+// Text component props: type, size, weight
+<Text type="body" size="regular" weight="normal">Content here</Text>
+
+// Heading component props: type
+<Heading type="titleL">Title here</Heading>
+
+// ❌ NEVER use typography tokens directly
+// ❌ NEVER hardcode font properties
+```
+
+## Verification Protocol (Before Submitting)
+
+Run this mental checklist:
+
+1. **Token Audit**: Search your code for:
+   - Regex: `['"]#[0-9a-fA-F]{3,8}['"]` → Should be ZERO matches
+   - Regex: `['"][0-9]+px['"]` → Should be ZERO matches (except in exceptional cases)
+   - All `color:`, `background:`, `padding:`, `margin:`, `gap:` use `theme.*`
+
+2. **Import Check**:
+   - All styled-components import `theme` from `@apify/ui-library`
+   - No duplicate component implementations
+
+3. **Pattern Match**:
+   - Compare your component structure to similar existing components
+   - Follow same prop naming conventions
+   - Use same variant patterns
+
+## Common Pitfalls (Avoid These)
+
+1. **❌ Mixing hardcoded and token values**
+   ```typescript
+   // ❌ WRONG
+   padding: ${theme.space.space16} 10px;
+
+   // ✅ CORRECT
+   padding: ${theme.space.space16} ${theme.space.space10};
+   ```
+
+2. **❌ Using non-existent color properties**
+   ```typescript
+   // ❌ WRONG
+   theme.color.neutral.textLight // doesn't exist
+   theme.color.primary.main // doesn't exist
+
+   // ✅ CORRECT
+   theme.color.neutral.textMuted // use actual property names
+   theme.color.primary.action // use actual property names
+   ```
+
+3. **❌ Not using available MCPs**
+   - If Storybook or Figma MCPs are available, use them
+   - They provide valuable context and patterns
+
+4. **❌ Over-reading for context**
+   - Read max 3 similar components
+   - Don't read entire directories
+   - Use Grep to find specific patterns
+
+## Figma Integration Workflow
+
+When user provides Figma design:
+
+1. **Get design context**:
+   ```
+   mcp__figma__get_design_context (with Figma URL)
+   ```
+
+2. **Extract design tokens**:
+   - Colors → Map to `theme.color.*`
+   - Spacing → Map to `theme.space.*`
+
+3. **Get screenshots if needed**:
+   ```
+   mcp__figma__get_screenshot (for visual reference)
+   ```
+
+4. **Verify variable mappings**:
+   ```
+   mcp__figma__get_variable_defs (to see Figma variables)
+   ```
+
+## Quick Reference Card
+
+| Property | Token Pattern | Example |
+|----------|---------------|---------|
+| Text color | `theme.color.{cat}.{prop}` | `theme.color.neutral.text` |
+| Background | `theme.color.{cat}.{prop}` | `theme.color.primary.background` |
+| Padding/Margin | `theme.space.space{N}` | `theme.space.space16` |
+| Gap | `theme.space.space{N}` | `theme.space.space8` |
+| Border radius | `theme.radius.radius{N}` | `theme.radius.radius8` |
+| Shadow | `theme.shadow.{name}` | `theme.shadow.shadow2` |
+| Typography | `<Text>` or `<Heading>` components | `<Text type="body" size="regular">` |
+
+**Note**: Use Storybook MCP or Grep (`src/web/src`) to discover all available token values.
+
+## Error Recovery
+
+If you realize you used hardcoded values:
+
+1. Immediately stop
+2. List all violations
+3. Fix ALL violations before proceeding
+4. Re-verify using audit checklist
+
+## Summary: The Non-Negotiables
+
+1. ✅ Check MCP availability and use if available (recommended)
+2. ✅ Use `theme.*` tokens for ALL styling values (colors, spacing, radius, shadows)
+3. ✅ Use `<Text>` and `<Heading>` components for typography (not tokens)
+4. ✅ Import components from `@apify/ui-library`
+5. ✅ Follow existing component patterns (read 1-3 examples)
+6. ✅ Use semantic color naming (category.property)
+7. ✅ Verify zero hardcoded values before submitting
+8. ❌ NEVER hardcode colors (#hex or rgb)
+9. ❌ NEVER hardcode spacing (Npx values)
+10. ❌ NEVER create duplicate components
+
+---
+
+**Enforcement**: Any UI code not following these rules must be rejected and refactored immediately.

DEVELOPMENT.md

@@ -82,11 +82,34 @@ What happens:
 - Editing files under `src/web/src/widgets/*.tsx` triggers a rebuild; the next widget render will use the updated code without restarting the server.
 
 Notes:
+- You can get your `APIFY_TOKEN` from [Apify Console](https://console.apify.com/settings/integrations)
 - Widget discovery happens when the server connects. Changing widget code is hot-reloaded; adding brand-new widget filenames typically requires reconnecting the MCP client (or restarting the server) to expose the new resource.
 - You can preview widgets quickly via the local esbuild dev server at `http://localhost:3000/index.html`.
 
 The MCP server listens on port `3001`. The HTTP server implementation used here is the standby Actor server in `src/actor/server.ts` (used by `src/main.ts` in STANDBY mode). The hosted production server behind [mcp.apify.com](https://mcp.apify.com) is located in the internal Apify repository.
 
+### Using MCP servers with Claude Code
+
+This repository includes a `.mcp.json` configuration file that allows you to use external MCP servers (like the Storybook MCP server) directly within Claude Code for enhanced development workflows.
+
+To use the Storybook MCP server (or any other MCP server that requires authentication), you need to configure your Apify API token in Claude Code's settings:
+
+1. Get your Apify API token from [Apify Console](https://console.apify.com/settings/integrations)
+2. Create or edit `.claude/settings.local.json` file
+3. Add the following environment variable configuration:
+
+```json
+{
+  "env": {
+    "APIFY_TOKEN": "<YOUR_APIFY_API_TOKEN>"
+  }
+}
+```
+
+4. Restart Claude Code for the changes to take effect
+
+The `.mcp.json` file uses environment variable expansion (`${APIFY_TOKEN}`) to securely reference your token without hardcoding it in the configuration file. This allows you to share the configuration with your team while keeping credentials private.
+
 ### Testing with MCPJam (optional)
 
 You can use [MCPJam](https://www.mcpjam.com/) to connect to and test the MCP server - run it using `npx @mcpjam/inspector@latest`.