# Pixasso

> The complete end-to-end frontend engineering and design orchestrator, skill, and Model Context Protocol (MCP) server for AI agents and humans.

Pixasso is an autonomous design-research and frontend engineering framework inspired by Picasso's multidisciplinary breadth. It guides coding agents and engineers through an end-to-end craft pipeline:
Intent Discovery -> Design Genome -> Decision Graph -> Capability Graph -> Task DAG -> Specialist Agents -> Automated QA.

- Web Showcase: https://pixasso.erebuzzz.tech
- Official npm Package: https://www.npmjs.com/package/pixasso-mcp (v1.2.1)
- Remote MCP Endpoint: https://mcp.pixasso.erebuzzz.tech/mcp (Streamable HTTP with GitHub OAuth, 200 calls/day allowance)
- Privacy Policy: https://github.com/Erebuzzz/pixasso/blob/main/PRIVACY.md
- MCP Registry Identifier: io.github.Erebuzzz/pixasso
- Skills.sh Registry: https://www.skills.sh/erebuzzz/pixasso/pixasso
- Cursor Plugin Directory: https://cursor.directory/plugins/pixasso
- GitHub Repository: https://github.com/Erebuzzz/pixasso

---

## Quickstart & Installation

### 1. Hosted Remote Endpoint (Zero Local Runtime)
Connect any remote-compatible MCP client directly to:
```text
https://mcp.pixasso.erebuzzz.tech/mcp
```
Secured with GitHub OAuth, 200 tool calls/day quota per user.

### 2. skills.sh (Universal for Cursor, Claude Desktop, Antigravity, Codex)
```bash
npx skills add Erebuzzz/pixasso
```

### 3. npm CLI / npx (Zero Install MCP Execution)
```bash
npx -y pixasso-mcp
```

### 4. Cursor IDE (`~/.cursor/mcp.json` or `.cursor/mcp.json`)
```json
{
  "mcpServers": {
    "pixasso": {
      "command": "npx",
      "args": ["-y", "pixasso-mcp"]
    }
  }
}
```

### 5. VS Code (`.vscode/mcp.json` or Cline / Roo Code settings)
```json
{
  "mcpServers": {
    "pixasso-remote": {
      "url": "https://mcp.pixasso.erebuzzz.tech/mcp"
    },
    "pixasso": {
      "command": "npx",
      "args": ["-y", "pixasso-mcp"]
    }
  }
}
```

### 6. Claude Desktop (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "pixasso": {
      "command": "npx",
      "args": ["-y", "pixasso-mcp"]
    }
  }
}
```

### 7. Claude Code CLI
```bash
claude mcp add pixasso npx -y pixasso-mcp
```

### 8. Google Antigravity (`~/.gemini/antigravity/mcp_config.json`)
```json
{
  "mcpServers": {
    "pixasso": {
      "command": "npx",
      "args": ["-y", "pixasso-mcp"]
    }
  }
}
```

### 9. Unified Local Clone Installer
```bash
git clone https://github.com/Erebuzzz/pixasso.git
cd pixasso
npm install
node scripts/install.js
```

### 10. Prompt for AI Assistant (Install in Any IDE)
Send this prompt to your AI coding assistant:
"Please configure the Pixasso MCP server for this project. Use either Hosted Remote (URL: https://mcp.pixasso.erebuzzz.tech/mcp) or Local Stdio (command: npx, args: ['-y', 'pixasso-mcp']) in the active editor's MCP configuration, and verify that the 7 Pixasso design tools are available."

---

## The 16 Frontend Architecture Pillars

1. UI and Visual Design: Semantic color scales, modular typography ratios, surface elevation, and design tokens.
2. Semantic HTML and JSX: Accessible landmark tags (`main`, `nav`, `article`, `header`), ARIA roles, and zero div soup.
3. Modern CSS Systems: CSS custom properties, container queries, Cascade Layers (`@layer`), subgrid, and zero-runtime styling.
4. TypeScript Excellence: Strict type checking, discriminated unions for UI state, zero `any`, and typed event handlers.
5. Framework Architecture: Component lifecycle, React 19, Next.js App Router, Svelte 5 runes, and Islands Architecture.
6. State Management: Server state caching (TanStack Query), client state (Zustand), and URL search params as source of truth.
7. API and Realtime Data: Type-safe REST, GraphQL, WebSockets, Server-Sent Events, and optimistic UI updates.
8. Client Authentication UX: Route protection guards, PKCE OAuth flows, token refresh queues, and zero credential flicker.
9. Forms and Input Validation: React Hook Form, Zod schema validation, accessible fieldsets, and inline error states.
10. Motion and WebGL 3D: Kinetic direction, Motion (motion.dev), GSAP timelines, Three.js shaders, and `prefers-reduced-motion`.
11. Responsive Multi-Device Design: Fluid typography (`clamp()`), container queries, and verified viewports (390px, 768px, 1024px, 1440px).
12. Accessibility (WCAG 2.2 AA/AAA): Screen reader tree navigation, keyboard traps, high-contrast focus rings, and ARIA live regions.
13. Core Web Vitals: LCP under 1.2s, INP under 100ms, zero CLS, streaming SSR, and image srcset optimization.
14. Frontend Testing: Vitest component unit tests, Playwright end-to-end tests, and automated visual regression sweeps.
15. Tooling and Bundling: Vite, Turbopack, Biome/ESLint linting, automated dependency updates, and container builds.
16. Deployment and Edge CDN: Edge runtime handlers, cache headers (`stale-while-revalidate`), atomic rollbacks, and CI/CD.

---

## MCP Server Tools Reference (JSON-RPC 2.0)

All tools declare the four official MCP directory hints: `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`.

### 1. `pixasso_discover_intent`
Initiates adaptive intent discovery across the 16 pillars and generates tailored popup questions for `ask_question`.
- Hints: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`
- Parameters:
  - `projectArchetype` (string, enum: `full_web_app`, `editorial_landing_page`, `creative_3d_canvas`, `design_system`, `general`)
  - `description` (string, required): Initial brief or problem description
  - `targetAudience` (string, optional): Target persona or demographic
  - `hasBrandIdentity` (boolean, optional): Whether existing brand guidelines exist or need to be synthesized from scratch
  - `referenceUrls` (array of strings, optional): Reference URLs capturing desired feel

### 2. `pixasso_search_references`
Queries all 40 curated knowledge resources (29 reference catalogs and 11 templates) across the 16 frontend pillars.
- Hints: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`
- Parameters:
  - `query` (string, required): Search keywords
  - `category` (string, enum: `all`, `reference`, `template`)
  - `tag` (string, optional): Tag filter (`typography`, `motion`, `a11y`, `3d`, `components`)

### 3. `pixasso_fetch_reference`
Fetches live website HTML server-side, extracts headings (h1-h4), links, metadata, and body text via Readability, and detects client-rendered SPAs (Framer, Webflow, React shells).
- Hints: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: false`, `openWorldHint: true`
- Parameters:
  - `url` (string, required): Target HTTP/HTTPS URL
  - `focus` (string, enum: `full`, `layout`, `typography`, `color`, `motion`)

### 4. `pixasso_generate_genome`
Validates design decisions and compiles a machine-readable `design-genome.yaml` specification with reference verification hard gate.
- Hints: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`
- Parameters:
  - `projectName` (string, required)
  - `themeMode` (string, enum: `paper`, `crt_mono`, `amoled_black`, `custom`)
  - `groundTone` (string, required, hex code)
  - `typography` (object, required: `displayFont`, `bodyFont`, `monoFont`, `scaleRatio`)
  - `colorTokens` (object, required: `primary`, `accent`, `border`)
  - `dimensionality` (string, enum: `2d_planar`, `2.5d_parallax`, `3d_webgl`)
  - `motionFeel` (string, optional)
  - `references` (array of objects, optional, verified references from `pixasso_fetch_reference`)

### 5. `pixasso_generate_brain`
Builds a Graphify-style Mermaid visualization mapping design decisions and Task DAG execution state.
- Hints: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`
- Parameters:
  - `projectName` (string, required)
  - `decisions` (array of objects with `category`, `choice`, `rationale`)
  - `tasks` (array of objects with `id`, `title`, `role`, `status`, `dependencies`)

### 6. `pixasso_audit_design`
Audits HTML, JSX, or CSS against generic AI clichés, accessibility guidelines, and the 16-pillar rubric.
- Hints: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`
- Parameters:
  - `componentMarkup` (string, required): Markup or CSS to evaluate
  - `contextDescription` (string, optional): Contextual design intent

### 7. `pixasso_generate_test_plan`
Generates an automated multi-viewport testing matrix (390px, 768px, 1024px, 1440px) and overflow detection script.
- Hints: `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`, `openWorldHint: false`
- Parameters:
  - `projectName` (string, required)
  - `testUrl` (string, optional)
  - `testedViewports` (array of numbers, optional: defaults to `[390, 768, 1024, 1440]`)


---

## Curated Knowledge Resources (`pixasso://`)
40 curated knowledge resources (29 references and 11 templates) available via `pixasso://`:

### References (`pixasso://references/{id}`)
- `frontend-architecture-pillars`: 16 foundational engineering pillars
- `discovery-framework`: Adaptive intent discovery question matrix
- `design-genome`: Epistemic states, tokens, and constraint persistence
- `design-brain`: Mermaid decision graphs and live Task DAG maps
- `typography-system`: Typography mathematics and modular scales
- `typography-discovery`: Deep hierarchy and readability inquiry
- `ui-component-libraries`: Curated UI components and registries
- `creative-coding-and-webgl`: ThreeUI, Spline 3D, and optical shaders
- `motion-and-animation`: Motion.dev, GSAP, spring physics, and easing
- `sound-and-sensory-design`: Web Audio API tactile audio synthesizer
- `interface-testing-and-qa`: Multi-viewport testing and overflow sweeps
- `inspiration-galleries`: 30+ visual, gaming HUD, and component galleries
- `anti-patterns-and-critique`: Impeccable AI Slop Catalog (65+ tropes)
- `art-direction-and-dimensions`: 2D vs 2.5D vs 3D spatial criteria
- `agent-orchestration`: Subagent delegation and tool coordination
- `task-graph`: Dependency-aware DAG execution pipelines
- `tool-registry`: Tool and MCP server capability mapping
- `contradiction-resolution`: Resolving conflicting design goals
- `generative-assets-and-tools`: Procedural SVGs and diffusion art prompts
- `live-case-studies`: Digital craft benchmark deconstructions
- `color-theory-and-harmony`: Geometric harmonies, 60-30-10, halation prevention
- `design-basics-and-visual-hierarchy`: Gestalt perception laws and 6 craft rules
- `component-and-section-archetypes`: Supahero.io heroes, bento geometry, navbars, footers
- `figma-mcp-and-agentic-ecosystem`: Figma MCP server, DESIGN.md specs, Rams 348-rule audit
- `creative-3d-and-blender-mcp`: Blender MCP server, Babylon.js, COBE globe, LiquidGL, Theatre.js
- `advanced-ui-components-and-telemetry`: KokonutUI, BklitUI telemetry, NumberFlow, Dotmatrix
- `anti-slop-writing-and-human-craft`: Human copy rules, tactile button physics, visual combinations
- `typography-and-font-foundries`: Fontshare, FreeFaces, futuristic fonts, Book of Shapes
- `web-craft-and-ergonomics`: Concentric radii math, eased gradients, OKLCH, tactile audio

### Templates (`pixasso://templates/{id}`)
- `component-implementation-spec`: Production component specification
- `interface-test-plan`: Multi-viewport testing matrix
- `design-brain`: Mermaid decision map template
- `design-brief`: Structured intake document
- `design-critique-rubric`: 5-pillar craft scorecard
- `design-genome`: YAML schema for design tokens
- `design-mode-spec`: Aesthetic mode definition
- `project-state`: Project phase tracking schema
- `task-graph`: Task Graph YAML DAG schema
- `typography-spec`: Typography specification schema
- `agent-task`: Specialist subagent task packet

---

## Master System Prompt for AI Agents

When acting as Pixasso, adhere to the core operating principle:
Intent -> Design Genome -> Decision Graph -> Capability Graph -> Task DAG -> Specialist Agents -> Validation.

Key Behavioral Guardrails:
1. Compulsory Interactive Discovery: Never assume styling. Inquire about aesthetic feel and architecture first using `ask_question`.
2. Zero Emdashes: Never use emdashes. Use colons, commas, parentheses, or hyphens for lists.
3. Low Emoji: Maintain professional restraint with minimal to zero emojis.
4. Human-Written Code Quality: Production-tested, semantic HTML5, WCAG AA accessible, responsive, and performant.
5. Anti-Pattern Guardrail: Eliminate generic AI tropes (purple gradients, Lucide flooding, universal scroll-fades, blanket glassmorphism).