Design system reference

Stack Design

En desarrollo

Sistema de diseño — Figma ↔ Vue

Cómo se corresponde la arquitectura de Figma con la arquitectura del front en Vue 3 + Tailwind v4, capa por capa.

Tesis: un design system debe organizarse por capas de dependencia y reutilización — no por complejidad visual — con correspondencia 1:1 entre la arquitectura de Figma y la del framework que lo implementa.

Índice

Parte I — Fundamentos

Pendiente Manifiesto — por qué Stack Design
Listo El modelo de 5 capas
Pendiente Glosario

Parte II — Arquitectura

Listo Arquitectura en Figma
Listo Cómo se lee la jerarquía en Figma
Listo Arquitectura de carpetas en Vue
Listo Resumen de la Convención de Archivos y Carpetas
Listo Tabla puente Figma ↔ Vue

Parte III — Reglas de implementación

Pendiente Normas y reglas de uso
Pendiente Guía de nomenclatura de variantes
Pendiente Conexión de estados de accesibilidad
Pendiente Plantilla de documentación de componente

Parte IV — Gobernanza

Pendiente Metadata de versión y changelog
Listo Cuándo usar 1 o 2 archivos en Figma
Pendiente Reglas de gobernanza

Parte V — Aplicado

Pendiente Mini ejemplo de ecommerce

Parte VI — Posicionamiento

Pendiente Stack Design vs. Atomic Design

Las 5 capas

De la utilidad más básica a la pantalla completa. Cada capa depende solo de la anterior — nunca al revés.

Tailwind primitives

Escala base sin semántica: colores, spacing, tamaños. No es una decisión de diseño, es la instalación de Tailwind.

Foundations

Variables semánticas definidas en Figma Variables — referencian los primitives, no valores crudos.

Components

Toda unidad reutilizable con nombre propio, simple o compuesta. Button y ProductCard viven en el mismo nivel.

Layouts / Templates

Estructura reutilizable de página: header, sidebar, grid de checkout sin distracciones.

Pages

Pantalla completa, una por ruta. Ensambla un layout con componentes.

Es la capa más abstracta y estable del documento — el modelo conceptual que no cambia aunque cambien los nombres de carpetas, el framework o la herramienta. Todo lo demás en esta guía deriva de estas 5 capas.

Tabla puente

Qué significa cada capa en Figma y dónde vive su equivalente en el código.

Concepto (Figma)	Qué es	Carpeta en Vue	Ejemplos
Tailwind primitives	Escala de utilidades sin semántica, provista por Tailwind v4.	— (instalación de Tailwind)	`gray-500` · `spacing-4` · `text-lg`
Foundations	Variables semánticas de Figma, exportadas a CSS.	shared/assets/	`color.brand.primary` · `size.button.md`
Components	Simples o compuestos — la complejidad interna no cambia dónde viven.	shared/components/ui\|layout/ o features/*/components/	AppButton, AppHeader (shared) · ProductCard, CartItem (feature)
Layouts / Templates	Estructura reutilizable de página.	layouts/	DefaultLayout, CheckoutLayout, AccountLayout
Pages	Pantalla completa, una por ruta.	features/*/views/	ProductDetailView, CartView, CheckoutView

Arquitectura de carpetas

Base: Feature-based architecture

Organización por dominio de negocio (features/), no por tipo de archivo. Cada bloque de la pestaña "Vista para diseño" corresponde a una fila de la tabla anterior.

src/
├── shared/
│   ├── components/
│   │   ├── ui/             // AppButton, AppModal, AppTabs, AppBadge
│   │   └── layout/          // AppHeader, AppFooter, AppSidebar
│   └── assets/
│       ├── tokens.json        // export de Figma Variables
│       └── theme.css          // @theme (Tailwind v4)
│
├── layouts/
│   ├── DefaultLayout.vue
│   ├── CheckoutLayout.vue
│   └── AccountLayout.vue
│
└── features/
    ├── pdl/              // Página de Listado de Producto
    │   ├── components/       // ProductCard, FilterPanel
    │   └── views/            // ProductListView.vue
    ├── pdp/              // Página De Producto
    │   ├── components/       // ProductHero, ProductDescription, ProductSpecs
    │   └── views/            // ProductDetailView.vue
    ├── cart/
    │   ├── components/       // CartDrawer, CartItem
    │   └── views/            // CartView.vue
    ├── checkout/
    │   ├── components/       // ShippingForm, PaymentForm
    │   └── views/            // CheckoutView.vue, OrderSuccessView.vue
    └── account/
        ├── components/
        └── views/

src/
├── core/                     // Infraestructura e inicialización
│   ├── api/                   // Instancia HTTP (Axios/Fetch)
│   └── config/                // Constantes globales y envs
│
├── features/                 // Módulos de negocio (todo en minúsculas)
│   ├── auth/
│   │   ├── components/        // LoginForm.vue, RegisterForm.vue
│   │   ├── views/              // LoginView.vue, RegisterView.vue
│   │   ├── composables/         // useLoginForm.ts
│   │   ├── routes/              // auth.routes.ts
│   │   ├── stores/               // auth.store.ts (estado del formulario)
│   │   ├── services/             // auth.service.ts
│   │   └── types/                 // auth.types.ts
│   │
│   ├── pdl/                // Página de Listado de Producto
│   │   ├── components/        // BookCard.vue, BookGrid.vue
│   │   ├── views/              // PdlView.vue
│   │   ├── composables/         // usePdlFilters.ts
│   │   ├── routes/              // pdl.routes.ts
│   │   ├── stores/               // pdl.store.ts
│   │   ├── services/             // pdl.service.ts
│   │   └── types/                 // pdl.types.ts
│   │
│   ├── pdp/                // Página De Producto
│   │   ├── components/        // ProductHero.vue, ProductDescription.vue, ProductSpecs.vue
│   │   ├── views/              // PdpView.vue
│   │   ├── composables/         // usePdpGallery.ts
│   │   ├── routes/              // pdp.routes.ts
│   │   ├── stores/               // pdp.store.ts
│   │   ├── services/             // pdp.service.ts
│   │   └── types/                 // pdp.types.ts
│   │
│   └── orders/
│       ├── components/        // OrderSummary.vue, OrderRow.vue
│       ├── views/              // OrdersView.vue
│       ├── composables/         // useCheckoutValidation.ts
│       ├── routes/              // orders.routes.ts
│       ├── stores/               // orders.store.ts (useCartTotals)
│       ├── services/             // orders.service.ts
│       └── types/                 // orders.types.ts
│
├── shared/                   // Design System, UI neutra y utilidades
│   ├── components/
│   │   ├── ui/                // BaseButton.vue, BaseInput.vue, BaseModal.vue
│   │   └── layout/             // AppHeader.vue, AppFooter.vue, AppSidebar.vue
│   ├── composables/            // useModal.ts, useDarkMode.ts, useDebounce.ts
│   ├── store/                  // useSessionStore.ts, useUiStore.ts
│   ├── utils/                  // format-date.ts, validators.ts
│   ├── types/                   // api.types.ts, common.types.ts
│   └── assets/
│       ├── tokens.json            // export de Figma Variables
│       ├── theme.css              // @theme (Tailwind v4)
│       └── images/               // fuentes, imágenes compartidas
│
├── layouts/                  // DefaultLayout.vue, AuthLayout.vue
├── router/                   // index.ts (orquestador general)
├── App.vue                    // Componente raíz (PascalCase)
└── main.ts                    // Punto de entrada

Resumen de la Convención de Archivos y Carpetas

Cómo se nombra cada tipo de archivo dentro de la arquitectura Vue, para que no haya ambigüedad entre features y entre personas.

Elemento	Convención	Ejemplo	Razón
Carpetas (todas)	`kebab-case` / lowercase	`features/pdl/`, `shared/ui/`	Consistencia cross-platform y terminal.
Componentes / Vistas	`PascalCase.vue`	`BookCard.vue`, `PdlView.vue`	Guía de estilo oficial de Vue 3.
Stores / Services / Routes	`camelCase.ts` o `kebab.type.ts`	`pdl.store.ts`, `pdl.routes.ts`	Identificación clara de la extensión técnica.
Composables	`camelCase.ts`	`useBookFilters.ts`	Prefijo `use` estándar de Composition API.
Utils / Helpers	`kebab-case.ts` o `camelCase.ts`	`format-currency.ts`	Funciones puras de JavaScript/TypeScript.

Arquitectura en Figma

En Figma la unidad no es "carpeta", es archivo → page → section → frame. La estructura Stack Design agrupa primero por dominio (1:1 exacto con features/*/ en Vue); la alternativa agrupa primero por tipo.

Stack Design · Archivo único (Design System + Ecommerce)

Page: Cover
Page: Foundations
├── Section: Color
├── Section: Typography
├── Section: Spacing & sizing
└── Section: Effects
Page: Components
├── Section: UI          // Button, Input, Modal, Tabs, Badge
└── Section: Layout       // Header, Footer, Sidebar
Page: Layouts
├── Section: DefaultLayout
├── Section: CheckoutLayout
└── Section: AccountLayout
Page: PDL
├── Section: Components   // ProductCard, FilterPanel
└── Section: Views         // Product list
Page: PDP
├── Section: Components   // ProductHero, ProductDescription, ProductSpecs
└── Section: Views         // Product detail
Page: Cart
├── Section: Components   // CartDrawer, CartItem
└── Section: Views         // Cart states
Page: Checkout
├── Section: Components   // ShippingForm, PaymentForm
└── Section: Views         // Shipping, Payment, Order review
Page: Account
├── Section: Components
└── Section: Views         // Order history, Profile
Page: Archive / WIP

Cómo se lee la jerarquía en Figma

En Figma la unidad no es "carpeta", es Archivo → Page → Section → Frame. Cada nivel contiene al siguiente, pero Components y Views son hermanas dentro de la misma Page — ninguna contiene a la otra.

La Section Views no incluye lo que hay en Components como si fuera una subcarpeta suya. El frame PDP se arma colocando instancias de ProductHero, ProductDescription y ProductSpecs sobre su propio lienzo — la definición original de cada componente sigue viviendo solo en Components.

Por qué 2 archivos

En ocasiones es recomendable utilizar dos archivos en lugar de uno. Estos son los casos:

1 archivo — cuándo

Una sola persona diseñando
Un solo producto
Fase de exploración o aprendizaje
El sistema todavía cambia a diario

2 archivos — cuándo

Más de una persona diseñando
Más de un producto consume el mismo sistema
Necesitas versionar y publicar el DS de forma independiente
Quieres evitar ediciones accidentales de componentes en pantallas de producto