inmmerce for VTEX

Tema, iconos, snippets e IntelliSense para quien construye en VTEX.

Los colores de sintaxis son los de Dracula, sobre el fondo más oscuro del Puelche: ahí cada color gana ~24% de contraste sobre el tema de origen, así que el código se lee de un vistazo.

Extensión de VS Code con todo lo que necesita un tema de VTEX IO Store Framework: snippets de bloques y props (con enums y validación) en store/blocks, rutas y contentSchemas, validación de JSON, autocompletado de las variables CSS del VTEX Style, y un tema de color con sus iconos de archivo y de interfaz.

Instalación

Desde el VS Code Marketplace: busca «inmmerce for VTEX», o instálala desde Quick Open (Cmd/Ctrl + P):

ext install commenteme.vtex-io-intellisense

Uso

1. Abre un tema de VTEX IO Store Framework.
2. En los archivos .json / .jsonc de store/ (por ejemplo store/blocks/*.jsonc), empieza a escribir el nombre de un bloque para disparar el snippet y el autocompletado.
3. Las props se autocompletan con sus enums y se validan contra el esquema de bloques (blocks.json, store/blocks/**/*.json, store/**/*.jsonc).

Las sugerencias son sensibles al contexto: el bloque completo sólo aparece en la raíz del archivo, donde de verdad se define; dentro de children / blocks / before / after / around se sugieren los ids ya definidos en el tema; y dentro de props sólo manda el esquema, con las propiedades del bloque.

No necesita configuración: la extensión activa las sugerencias dentro de strings para json / jsonc y la validación de JSON se enciende sola en esos archivos.

Variables CSS del VTEX Style

En archivos css, scss, less y postcss la extensión también autocompleta las CSS custom properties que VTEX expone en runtime a partir de tu JSON de tokens (el mismo formato del style.json nativo): var(--emphasis), var(--spacing-2), var(--type-scale-1), var(--background-action-primary)…

• Se dispara al escribir - o (. Si el cursor ya está dentro de var(, inserta sólo el nombre; si no, inserta var(--nombre) completo.
• Las variables de color se muestran con su swatch (color preview) y el valor.

Origen de los tokens (por prioridad): primero styles/configs/tokens.json, luego tokens.json en la raíz del workspace, y si no hay ninguno cae a un tokens.json embebido en la extensión con los valores por defecto de VTEX. Los cambios en cualquier tokens.json se recargan solos.

Comando VTEX: Aplicar ajustes de conforto del Puelche (paleta de comandos): escribe en tus ajustes de usuario la fuente recomendada, las ligaduras, el tamaño, la altura de línea y los tres temas del Puelche, después de mostrarte valor actual → valor nuevo clave por clave. Si la fuente no está instalada, te avisa y te copia el comando de instalación en vez de apuntar a una fuente inexistente. VTEX: Deshacer ajustes de conforto vuelve atrás.

La fuente recomendada es Google Sans Code, con sus ejes variables activados. No trae ligaduras —su tabla GSUB no tiene liga ni calt—, pero el preset deja fontLigatures activo por si entra otra fuente en la pila.

brew install --cask font-google-sans-code

Comando VTEX: Gerar tokens.css (paleta de comandos, Cmd/Ctrl + Shift + P): exporta un :root { ... } con todas las variables generadas, guardado junto al JSON de origen.

El tema Puelche

Un tema oscuro y de baja saturación, pensado para sesiones largas: la identidad de la extensión vive en el chrome de la interfaz (cursor, pestaña activa, badges), no en el resaltado de sintaxis, que se queda tranquilo para que puedas leer código durante horas.

Actívalo con Cmd/Ctrl + K seguido de Cmd/Ctrl + T y elige Puelche en la lista.

Colorea por papel, no por lenguaje

Hay 9 papeles semánticos y todos los lenguajes se mapean sobre esos mismos 9. Una etiqueta HTML, un componente JSX, un selector de elemento CSS, un decorador de Python, un atributo de Prisma, una directiva de GraphQL y un título de Markdown reciben el mismo color, porque todos son "estructura con nombre". Aprendes el mapa una vez y sirve para todos los archivos.

Legibilidad

• Los comentarios no están apagados: quedan en 5.85:1 de contraste, por encima del mínimo de accesibilidad. Un comentario que no se lee es un comentario que no se escribe.
• El cuerpo de texto de Markdown se queda sin color, para que un README siga leyéndose como prosa y no como código.
• La cursiva sustituye a los colores extra: comentarios, parámetros, self / cls, atributos HTML y JSX, import / from y blockquote. Un matiz más, no un color más.
• El color de acento sólo aparece en el chrome (cursor, pestaña activa, badge). Nunca colorea texto de código.

Iconos de archivo y carpeta

72 dibujos propios, coloreados con el mismo esquema de papeles que el tema, así que el explorador y el editor hablan el mismo idioma visual.

Cada icono son dos capas: una silueta sólida —la carpeta, o la hoja de papel— con el color del papel semántico, y encima la marca de lo que contiene, trazada en un tono oscuro del mismo color. La razón es el tamaño real: en el explorador el icono se dibuja a 16px, y ahí un trazo de 1.33px se pierde sobre el fondo oscuro mientras que una mancha sólida se lee de un vistazo. El tono oscuro no se elige a ojo: es el mismo color del papel mezclado al 60% con el fondo del editor.

Actívalos desde la paleta de comandos (Cmd/Ctrl + Shift + P) con Preferences: File Icon Theme → Puelche.

Lo que los diferencia de un pack genérico es que cubren la estructura real de una app de VTEX IO: icono propio para las carpetas store, react, node, graphql, messages, pixel, admin y styles, y para los archivos manifest.json, routes.json, blocks.json, interfaces.json, style.json y .vtexignore.

La cobertura sigue la estructura real de un tema: cada builder de VTEX IO tiene su carpeta —store, react, node, graphql, messages, styles, admin, pixel, assets, docs, checkout-ui-custom, sitemap, masterdata, configuration—, y también las carpetas de dentro del tema: store/blocks, store/templates, styles/iconpacks, y las páginas de la tienda (home, product, search, header, footer, landing, cart, account). En total, ~80 extensiones, 79 nombres de archivo, 117 nombres de carpeta y 26 languageIds.

Los nombres conocidos llevan marca propia, aunque la extensión diga otra cosa: en VS Code fileNames gana a fileExtensions, así que CLAUDE.md y AGENTS.md llevan el sunburst de Claude y no el icono de Markdown. Igual con npm, yarn, Prettier, ESLint, Docker, Git, GitHub y VTEX. Son interpretaciones redibujadas para los 16px del explorador, no el asset oficial: a ese tamaño la fidelidad se pierde y lo que queda es la silueta.

Iconos de la interfaz

El product icon theme reemplaza los iconos de la propia UI de VS Code por un conjunto propio, monoline: 58 glifos dibujados a mano que cubren la barra de actividad, el layout y la barra de título, la barra de estado, el árbol del explorador, pestañas y editor, paneles, acciones comunes y feedback. Se sirven como 93 entradas, porque 35 codicons distintos comparten dibujo con otro.

Actívalo desde la paleta de comandos con Preferences: Product Icon Theme → Puelche.

La cobertura es parcial a propósito: los iconos que no están cubiertos siguen usando el codicon nativo de VS Code, que siempre se verá mejor que un dibujo forzado. Para que la mezcla no se note, la fuente usa las mismas métricas que el codicon nativo (unitsPerEm 1000, razón 1.0), así que los glifos propios y los nativos comparten línea base y tamaño.

Solución de problemas

No aparece ninguna sugerencia de bloque. Sólo se ofrecen en archivos bajo store/, y el bloque completo únicamente en la raíz del archivo. Dentro de props es intencional que no aparezca: ahí sólo caben propiedades.

Ctrl + Espacio no abre las sugerencias (macOS). macOS se queda con ese atajo para Seleccionar la fuente de entrada anterior, así que nunca llega a VS Code. Dos salidas:

• Usa Cmd + I, que también dispara las sugerencias en VS Code.
• O libera el atajo en Ajustes del Sistema → Teclado → Atajos de teclado → Fuentes de entrada y desmarca Seleccionar la fuente de entrada anterior.

vtex-io-snippets es open source bajo licencia MIT.

Hecho con amor y café por zeluizr y con la ayuda de Claude ☕