pixasso

# Pixasso

> **The Complete End-to-End Frontend Engineering & Design Orchestrator for AI Agents and Humans.**

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![MCP Server](https://img.shields.io/badge/MCP%20Server-JSON--RPC%202.0-orange)](mcp-server/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.8-blue)](mcp-server/src/)
[![Platform Support](https://img.shields.io/badge/Platforms-Cursor%20|%20Antigravity%20|%20Claude%20|%20VS%20Code-brightgreen)](scripts/install.js)
[![Live](https://img.shields.io/badge/Live%20Showcase-pixasso.erebuzzz.tech-purple)](https://pixasso.erebuzzz.tech)

Live Documentation and Showcase: **[pixasso.erebuzzz.tech](https://pixasso.erebuzzz.tech)**

---

## Overview

Pixasso is a senior design-research, intent-discovery, and full-spectrum frontend engineering orchestrator inspired by Picasso's exploratory breadth. It rejects cookie-cutter AI interfaces, purple gradients, Lucide icon flooding, and superficial templates. Instead, Pixasso guides autonomous coding agents (and human engineers) through a rigorous pipeline:

```text
Intent Discovery -> Design Genome -> Decision Graph -> Capability Graph -> Task DAG -> Specialist Agents -> Automated QA
```

Pixasso unifies **Art Direction**, **UX Architecture**, **Typography Direction**, **Motion Systems**, **Full-Stack Frontend Implementation**, and **Automated Multi-Viewport Testing** into a single cohesive skill and Model Context Protocol (MCP) server.

---

## Visual Showcase & Themes

Pixasso supports multi-mode aesthetic execution tailored to your product identity:

| Theme | Aesthetic Mode | Key Visual Traits |
| :--- | :--- | :--- |
| **Paper Light** | Architectural Editorial | Warm ivory (`#fbfaf7`), hairlines, wide grotesque display headlines, Newsreader serif body |
| **CRT Terminal** | Retro Phosphor Computing | Phosphor emerald (`#00ff66`), scanlines, cathode vignette, bracket hotkeys `[B]`, monospace telemetry |
| **Pitch Black AMOLED** | Deep Space Operations | True `#000000` ground, cold metallic accents, sharp geometric borders, maximum contrast |

### Interface Previews

![Pixasso Paper Light Theme](assets/screenshots/pixasso-hero-paper.png)
*Figure 1: Architectural Paper Light Theme with wide display headlines and generative wave synthesizer.*

![Pixasso CRT Terminal Theme](assets/screenshots/pixasso-hero-crt.png)
*Figure 2: Retro Cathode Ray Terminal Theme with phosphor glow, scanline shader, and telemetry HUD.*

![Pixasso AMOLED Pitch Black Theme](assets/screenshots/pixasso-hero-amoled.png)
*Figure 3: Pitch Black AMOLED Theme optimized for high-contrast, edge-density operational dashboards.*

![Pixasso Responsive Mobile Viewport](assets/screenshots/pixasso-mobile-preview.png)
*Figure 4: Mobile Viewport (390px) verified with zero horizontal DOM overflow and accessible touch targets.*

![Pixasso 3D Kinetic Sculpture](assets/screenshots/pixasso-3d-sculpture.png)
*Figure 5: 3D Kinetic Sculpture with procedural faceted cage, PBR metallic core, and orbital gimbal rings.*

![Pixasso 3D Gravitational Particle Galaxy](assets/screenshots/pixasso-3d-galaxy.png)
*Figure 6: 15,000 GPU particle galaxy in CRT phosphor mode with mouse gravitational attraction vectors.*

![Pixasso 3D Spatial Hardware Exploded View](assets/screenshots/pixasso-3d-exploded.png)
*Figure 7: 5-Layer precision hardware assembly with interactive exploded-view disassembly slider and callouts.*

---

## The 16 Pillars of Frontend Architecture

Pixasso treats frontend engineering not as shallow visual styling, but as a complete 16-pillar software engineering discipline:

| Pillar | Discipline | Key Technical Responsibilities |
| :--- | :--- | :--- |
| **1. UI & Visual Design** | Design Systems & Tokens | Semantic color scales, modular typography scales, surface depth, spacing systems |
| **2. Semantic HTML & JSX** | Document Structure | Accessible landmarks (`main`, `nav`, `article`), ARIA roles, microdata, zero `div` soup |
| **3. Modern CSS Systems** | Styling Architecture | CSS custom properties, container queries, Cascade Layers (`@layer`), subgrid, zero-runtime CSS |
| **4. TypeScript Excellence** | Type Safety | Strict mode, discriminated unions for UI state, zero `any`, typed event handlers |
| **5. Framework Architecture** | Component Lifecycle | React 19, Next.js App Router, Svelte 5 runes, Vue 3 Composition, Islands Architecture |
| **6. State Management** | Data Flow & Cache | Server state (TanStack Query), client state (Zustand), URL search params as source of truth |
| **7. API & Realtime Data** | Network Transport | Type-safe REST, GraphQL, WebSockets, Server-Sent Events, optimistic UI mutations |
| **8. Client Authentication UX** | Session Security | Route protection guards, PKCE OAuth flows, token refresh queues, zero credential flicker |
| **9. Forms & Input Validation** | Data Integrity | React Hook Form, Zod schema validation, inline error hints, accessible fieldsets |
| **10. Motion & Animation** | Kinetic Direction | Motion (motion.dev), GSAP timelines, WebGL canvas shaders, `prefers-reduced-motion` |
| **11. Responsive Design** | Viewport Versatility | Fluid typography (`clamp()`), container queries, adaptive layouts (390px to 2560px+) |
| **12. Accessibility (WCAG)** | Inclusive Design | WCAG 2.2 AA/AAA compliance, screen reader tree, keyboard traps, focus rings, ARIA live |
| **13. Core Web Vitals** | Performance Budget | LCP under 1.2s, INP under 100ms, CLS at 0, streaming SSR, image srcset optimization |
| **14. Frontend Testing** | Verification Suite | Vitest component unit tests, Playwright end-to-end tests, visual regression checks |
| **15. Tooling & Bundling** | Developer Experience | Vite, Turbopack, Biome/ESLint linting, automated dependency updates, Docker images |
| **16. Deployment & CDN** | Production Release | Edge runtime, CDN cache headers (`stale-while-revalidate`), atomic rollbacks, CI/CD |

---

## System Architecture

```mermaid
flowchart TB
    subgraph ClientLayer ["Client & IDE Integration"]
        Cursor["Cursor IDE"]
        Claude["Claude Desktop & Claude Code"]
        Antigravity["Google Antigravity & Gemini"]
        Codex["VS Code / Codex / Custom Agents"]
    end

    subgraph Protocol ["Transport Layer"]
        JSONRPC["Model Context Protocol (JSON-RPC 2.0 over Stdio)"]
        SkillsShim["Native Skills Runtime (SKILL.md)"]
    end

    subgraph PixassoCore ["Pixasso Engine"]
        Discovery["Adaptive Intent Discovery Matrix"]
        Genome["Design Genome Engine (YAML + Brain)"]
        TaskDAG["Dependency-Aware Task DAG"]
        Orchestrator["Specialist Agent Dispatcher"]
    end

    subgraph KnowledgeHub ["Curated Knowledge Catalogs"]
        Pillars["16 Frontend Architecture Pillars"]
        TypeSpec["Typography Systems & Variable Fonts"]
        MotionSpec["Motion Choreography & Spring Physics"]
        SensorySpec["Web Audio API UISFX Engine"]
        QASpec["Multi-Viewport & DOM Overflow Verification"]
    end

    subgraph Specialists ["Specialist Agent Roles"]
        ArtDir["Art Director"]
        UXArch["UX Architect"]
        TypeDir["Typography Director"]
        FrontArch["Frontend Architect"]
        QAEng["Interface QA Engineer"]
    end

    subgraph Delivery ["Shipped Artifacts"]
        Site["pixasso.erebuzzz.tech"]
        CodeProd["Production Component Code"]
        DesignBrain["Graphify Design Brain (.md)"]
        TestPlan["Operational Test Plan (.md)"]
    end

    ClientLayer --> Protocol
    Protocol --> PixassoCore
    PixassoCore <--> KnowledgeHub
    PixassoCore --> Specialists
    Specialists --> Delivery
```

---

## Operating Principle: Intent to Validation

Pixasso enforces a structured workflow that turns user intent into verified production code:

```mermaid
flowchart LR
    A["Intent Discovery<br/>(ask_question)"] --> B["Design Genome<br/>(Tokens & Modes)"]
    B --> C["Design Brain<br/>(Mermaid Graph)"]
    C --> D["Reference Analysis<br/>(Benchmarks)"]
    D --> E["Task DAG<br/>(Dependencies)"]
    E --> F["Specialist Agents<br/>(Code & Motion)"]
    F --> G["Interface Testing<br/>(Multi-Viewport QA)"]
    G --> H["Final Verification<br/>(Shipped UI)"]
```

```mermaid
sequenceDiagram
    autonumber
    actor User as Developer / Designer
    participant Pixasso as Pixasso Orchestrator
    participant MCP as Pixasso MCP Server
    participant Genome as Design Genome
    participant Agents as Specialist Agents
    participant QA as Automated Interface QA

    User->>Pixasso: Request interface or application
    Pixasso->>User: Compulsory Popup Questions (ask_question)
    User-->>Pixasso: Theme, typography, dimensionality, conversion goals
    Pixasso->>MCP: pixasso_generate_genome
    MCP-->>Genome: Structured Design Genome (YAML)
    Pixasso->>MCP: pixasso_generate_brain
    MCP-->>Pixasso: Mermaid Decision Tree and Task DAG
    Pixasso->>Agents: Dispatch concurrent implementation tasks
    Agents-->>Pixasso: Production HTML5, Tailwind, TypeScript, Motion code
    Pixasso->>QA: Multi-viewport audit (390px, 768px, 1024px, 1440px)
    QA-->>Pixasso: Zero DOM overflow and accessibility sign-off
    Pixasso->>User: Verified components, live preview, and test report
```

---

## Compulsory Popup Discovery Gate

Pixasso strictly forbids assuming generic defaults or hiding questions inside plans. Before generating code or planning architectures, agents must call `ask_question` across key dimensions:

```mermaid
flowchart TD
    Prompt["User Prompts New Project"] --> Popup["Compulsory Interactive Popup Modal (ask_question)"]

    subgraph Matrix ["Adaptive Discovery Matrix"]
        D1["Narrative & Theme<br/>(Paper, CRT-mono, Pitch Black, Brutalist, Editorial)"]
        D2["Typography Hierarchy<br/>(Display sans, warm editorial serif, technical mono)"]
        D3["Dimensionality Mode<br/>(2D Planar, 2.5D Parallax, 3D WebGL / Spline)"]
        D4["Sensory Feedback<br/>(Web Audio UISFX synthesized clicks and snaps)"]
        D5["Pillar