Instalación y primeros pasos

Opciones de instalación

OpenPencil se puede usar de cinco maneras diferentes según tu flujo de trabajo y preferencias. Cada una tiene ventajas distintas.

flowchart TD
    A[¿Cómo quieres usar OpenPencil?] --> B{¿Necesitas instalación local?}
    B -- No --> C[Web PWA<br/>app.openpencil.dev]
    B -- Sí --> D{¿Sistema operativo?}
    D -- macOS --> E[Homebrew Cask]
    D -- Windows --> F[Scoop]
    D -- Linux --> G{¿Prefieres contenedor?}
    G -- Sí --> H[Docker]
    G -- No --> I[AppImage / snap]
    E --> J[CLI op disponible]
    F --> J
    H --> J
    I --> J

Opción 1: Versión web (PWA)

La forma más rápida de empezar es la versión web en app.openpencil.dev. Es una Progressive Web App completa: puedes instalarla en tu sistema operativo desde el navegador y funciona offline una vez cargada.

Ventajas: Sin instalación, acceso inmediato, siempre en la última versión.
Limitaciones: Sin acceso al CLI op, performance ligeramente inferior al cliente nativo.

Para instalarla como app de escritorio desde Chrome o Edge: menú → “Instalar OpenPencil” o busca el ícono de instalación en la barra de direcciones.

Opción 2: macOS con Homebrew

# Agregar el tap del proyecto
brew tap zseven-w/openpencil

# Instalar la app de escritorio
brew install --cask openpencil

# Verificar instalación
op --version

Homebrew instala tanto la aplicación de escritorio (Electron) como el CLI op en tu PATH. Puedes actualizar con brew upgrade openpencil.

Opción 3: Windows con Scoop

# Agregar el bucket de OpenPencil
scoop bucket add openpencil https://github.com/zseven-w/scoop-openpencil

# Instalar
scoop install openpencil

# Verificar
op --version

Scoop es preferible a Chocolatey para OpenPencil porque gestiona las actualizaciones de forma más predecible. Si no tienes Scoop instalado: irm get.scoop.sh | iex en PowerShell.

Opción 4: CLI global via npm/bun

Si solo quieres el CLI sin la aplicación de escritorio:

# Con npm
npm install -g @zseven-w/openpencil

# Con bun (más rápido)
bun install -g @zseven-w/openpencil

# Con pnpm
pnpm add -g @zseven-w/openpencil

# Verificar
op --version
op help

Esta es la opción ideal para entornos de CI/CD donde no necesitas la interfaz gráfica.

Opción 5: Docker

Para entornos de servidor o cuando quieres aislar la instalación:

# Iniciar el servidor de OpenPencil
docker run -d \
  -p 3000:3000 \
  -v $(pwd)/designs:/app/designs \
  --name openpencil \
  ghcr.io/zseven-w/openpencil:latest

# Acceder en http://localhost:3000

Con Docker Compose, puedes crear un docker-compose.yml para tu proyecto:

services:
  openpencil:
    image: ghcr.io/zseven-w/openpencil:latest
    ports:
      - "3000:3000"
    volumes:
      - ./designs:/app/designs
      - ./exports:/app/exports
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
    restart: unless-stopped

Configuración inicial

Al abrir OpenPencil por primera vez, el asistente de configuración te pregunta sobre tus preferencias de IA.

Configurar proveedores de IA

OpenPencil puede funcionar sin IA (como editor de diseño puro), pero gran parte de su valor viene de las funciones de IA. Para configurarlas:

1. Abre Preferencias (Cmd+, en macOS, Ctrl+, en Windows/Linux)
2. Ve a la sección Agentes
3. Agrega las API keys de los proveedores que quieras usar

// ~/.config/openpencil/config.json
{
  "ai": {
    "providers": {
      "anthropic": {
        "apiKey": "sk-ant-...",
        "defaultModel": "claude-opus-4-5"
      },
      "openai": {
        "apiKey": "sk-...",
        "defaultModel": "gpt-4o"
      }
    },
    "defaultProvider": "anthropic",
    "agentLevel": "full"
  },
  "editor": {
    "theme": "dark",
    "language": "es",
    "autosave": true,
    "autosaveInterval": 30
  }
}

También puedes configurarlo via CLI:

op config set ai.providers.anthropic.apiKey "sk-ant-..."
op config set ai.defaultProvider "anthropic"

La interfaz de usuario

OpenPencil tiene una interfaz familiar para cualquiera que haya usado Figma o Sketch, pero con algunas diferencias importantes.

graph LR
    subgraph UI["Interfaz de OpenPencil"]
        A[Toolbar<br/>izquierda] --> |herramientas| B[Canvas<br/>central]
        C[Panel páginas<br/>izquierda] --> B
        B --> D[Panel propiedades<br/>derecha]
        E[Barra superior] --> B
        F[Chat IA<br/>Cmd+J] --> B
    end

Barra de herramientas (izquierda)

• V — Herramienta de selección
• R — Rectángulo
• O — Elipse/círculo
• T — Texto
• P — Pen/Bezier (paths personalizados)
• L — Línea
• I — Picker de color (eyedropper)
• H — Mano (pan del canvas)
• Z — Zoom

Panel de páginas (izquierda inferior)

Lista de páginas del documento. Puedes agregar, renombrar, duplicar y reordenar páginas. Cada página tiene su propio canvas infinito.

Canvas central

El área de trabajo. El canvas es virtualmente infinito y soporta múltiples frames (artboards) en el mismo espacio. Puedes organizar variantes, flujos y estados de la misma pantalla en un único canvas.

Panel de propiedades (derecha)

Muestra las propiedades del nodo seleccionado: posición, tamaño, fills, strokes, efectos, tipografía (para texto), auto-layout (para frames) y más.

Barra superior

Nombre del documento, controles de zoom, accesos rápidos a exportación y colaboración, y el selector de página activa.

Navegación del canvas

La navegación eficiente del canvas es fundamental para trabajar bien. OpenPencil usa los mismos atajos que la mayoría de herramientas de diseño:

Acción	Atajo
Pan (desplazar)	Espacio + arrastrar, o botón medio del ratón
Zoom in	Cmd/Ctrl + + o scroll hacia arriba
Zoom out	Cmd/Ctrl + - o scroll hacia abajo
Zoom para encajar	Cmd/Ctrl + 0
Zoom al 100%	Cmd/Ctrl + 1
Seleccionar todo	Cmd/Ctrl + A
Deshacer	Cmd/Ctrl + Z
Rehacer	Cmd/Ctrl + Shift + Z

Para navegar rápidamente en documentos grandes, el mini-mapa en la esquina inferior derecha muestra una vista panorámica del canvas con un indicador de la vista actual.

Primer archivo .op

Vamos a crear nuestro primer diseño desde cero. Abre OpenPencil y sigue estos pasos.

Crear un nuevo documento

Al iniciar, OpenPencil muestra la pantalla de inicio con documentos recientes. Haz click en Nuevo documento o usa Cmd/Ctrl + N.

El documento se crea con una página llamada “Página 1” y un canvas vacío. El archivo aún no tiene nombre; se nombrará cuando guardes con Cmd/Ctrl + S.

# También puedes crear un nuevo documento desde el CLI
op new mi-proyecto.op
op start mi-proyecto.op  # Abre en la app de escritorio

Crear el primer frame (artboard)

Un frame en OpenPencil es equivalente a un artboard en Figma o Sketch. Es el contenedor principal de tus diseños.

1. Selecciona la herramienta Frame con la tecla F
2. Haz click y arrastra en el canvas para definir el tamaño
3. O en el panel derecho, con el frame seleccionado, selecciona un preset (iPhone 16, iPad, Desktop 1440, etc.)

Para este ejercicio, crea un frame de 1440×900 para una pantalla de escritorio:

• Pulsa F
• En el panel derecho busca “Desktop” en los presets

Primeras formas

Con el frame creado, vamos a agregar elementos básicos.

Rectángulo:

1. Pulsa R para activar la herramienta rectángulo
2. Haz click y arrastra dentro del frame
3. En el panel derecho puedes ajustar posición exacta (X, Y), tamaño (W, H), radio de esquina y fills

Texto:

1. Pulsa T para activar la herramienta de texto
2. Haz click donde quieres el texto (texto en línea) o arrastra para definir un contenedor de texto
3. El editor de texto tiene opciones de tipografía en el panel derecho: fuente, tamaño, peso, leading, tracking, alineación

Elipse/círculo:

1. Pulsa O
2. Para un círculo perfecto, mantén Shift mientras arrastras

Selección y transformación

Con la herramienta de selección (V):

• Click: Selecciona el nodo más superficial
• Click en espacio vacío: Deselecciona todo
• Click sostenido + arrastrar: Selección por área (rubber band)
• Click + Shift: Agrega/quita de la selección
• Doble click: Entra al grupo o frame
• Escape: Sube un nivel en la jerarquía

Para mover un nodo: selecciónalo y arrastra, o usa las flechas del teclado (con Shift se mueven de 10px en 10px).

Para redimensionar: arrastra las manijas de las esquinas. Shift mantiene la proporción. Alt/Option redimensiona desde el centro.

Alineación

Con múltiples nodos seleccionados, el panel derecho muestra opciones de alineación:

• Alinear al borde izquierdo, derecho, superior, inferior
• Centrar horizontal o verticalmente
• Distribuir con espaciado uniforme

También puedes alinear respecto al frame padre: mantén Cmd/Ctrl mientras alineas.

Auto-guardado y el formato .op

OpenPencil guarda automáticamente cada 30 segundos (configurable). El archivo se guarda en formato .op, que es JSON:

# Ver el contenido del archivo
cat mi-proyecto.op | python3 -m json.tool

# O con jq si lo tienes instalado
cat mi-proyecto.op | jq '.pages[0].nodes | length'

Esto hace que los archivos .op sean perfectamente versionables en Git:

# En tu repositorio
git add designs/mi-proyecto.op
git commit -m "feat: agregar wireframe de pantalla de inicio"

# Ver diferencias entre versiones
git diff HEAD~1 designs/mi-proyecto.op

Importar diseños existentes

Si vienes de Figma, puedes importar tus diseños:

# Importar un archivo Figma
op import:figma export-figma.fig --output mi-proyecto.op

# También desde la UI: File → Import → Figma file

La importación preserva:

• Estructura de páginas y frames
• Componentes y estilos
• Variables de diseño (tokens)
• Fuentes (las no disponibles se marcan como faltantes)
• Grids y guías

Algunos elementos complejos de Figma como los plugins de terceros o el Advanced Prototyping no se importan.

Configurar el entorno de desarrollo

Para sacar el máximo partido al CLI, configura algunas variables de entorno útiles:

# ~/.zshrc o ~/.bashrc
export OPENPENCIL_API_KEY="sk-ant-..."  # Si usas la API
export OPENPENCIL_DESIGNS="$HOME/Diseños"  # Carpeta de proyectos

# Aliases útiles
alias opd="op design"
alias ope="op export react"
alias opw="op start"

Verifica que todo funciona:

op doctor  # Diagnóstico del entorno
op --version  # Versión instalada
op help  # Lista de comandos disponibles

Primer diseño con IA

Antes de profundizar en las herramientas manuales, vamos a experimentar con el chat de IA para entender el potencial de OpenPencil.

1. Crea un nuevo documento
2. Agrega un frame de 1440×900
3. Selecciona el frame
4. Abre el chat con Cmd+J
5. Escribe: “Diseña una barra de navegación para una app de gestión de tareas con logo, links de menú y un botón de acción principal”

El agente procesará la solicitud en tres fases:

• Skeleton: Define la estructura y layout de la navegación
• Content: Agrega el contenido real (textos, iconos)
• Refine: Ajusta colores, tipografía y espaciado

En los siguientes capítulos exploraremos cada herramienta en profundidad y aprenderemos a dominar tanto el canvas manual como el asistente de IA.

Resumen

En este capítulo has aprendido a:

• Instalar OpenPencil en cualquier plataforma (nativo, web, Docker, CLI)
• Configurar los proveedores de IA
• Navegar la interfaz de usuario
• Crear frames, formas básicas y texto
• Entender el formato .op y su compatibilidad con Git
• Importar diseños desde Figma

En el próximo capítulo exploraremos en profundidad todas las herramientas de diseño del canvas.