Evolución de Design Tokens - De Arquitectura Monobrand a Multibrand

Descripción

Este proyecto documenta la evolución arquitectónica del paquete de Design Tokens de Código Obsidiana, transformándose de un sistema de tokens de una sola marca en una plataforma multimarca sofisticada. La evolución aborda la creciente necesidad de soportar múltiples líneas de productos manteniendo consistencia, escalabilidad y experiencia de desarrollador.

La transformación introdujo configuración dinámica de marcas, pipelines de construcción avanzados y un sistema jerárquico de herencia de tokens que permite a las marcas compartir fundamentos de diseño comunes mientras expresan sus identidades visuales únicas a través de la precisión del espacio de color OKLCH.

Desafíos

Gestión de Tokens Multimarca: Escalar desde un sistema de una sola marca para soportar múltiples marcas (Obsidiana, Ixiptla) sin duplicación de código, manteniendo estructuras de tokens consistentes y validación en todas las marcas
Arquitectura de Construcción Dinámica: Rediseñar el sistema de construcción para generar salidas específicas por marca desde tokens base compartidos, requiriendo configuración dinámica de Style Dictionary y gestión compleja de rutas de exportación
Herencia y Sobrescritura de Tokens: Crear un sistema jerárquico donde las marcas puedan heredar tokens de diseño base mientras sobrescriben valores específicos, asegurando consistencia en estructura pero flexibilidad en expresión de marca
Complejidad de Distribución de Paquetes: Evolucionar desde exportaciones simples de una sola entrada a importaciones sofisticadas basadas en rutas soportando patrones @package/brand y @package/brand/css manteniendo compatibilidad hacia atrás
Estrategia de Testing Avanzada: Escalar cobertura de pruebas para validar consistencia de tokens a través de múltiples marcas, asegurando paridad estructural, validación de valores OKLCH y testing de compatibilidad inter-marca

Soluciones

Arquitectura Multimarca con Herencia de Tokens: Implementé un sistema jerárquico de tokens separando tokens base compartidos de sobrescrituras específicas por marca. La arquitectura usa un directorio base/ para elementos de diseño comunes (espaciado, radio de bordes, efectos) y directorios brands/ para paletas de colores específicas de marca y personalizaciones.

Estructura Jerárquica de Tokens

// Tokens base compartidos entre todas las marcas
src/tokens/base/
  ├── design.tokens.json    // Espaciado, bordes, efectos
  ├── font.tokens.json      // Escalas tipográficas
  └── design.tokens.spec.ts // Validación base

// Tokens específicos por marca
src/tokens/brands/
  ├── obsidiana/
  │   ├── color.tokens.json      // Paleta de colores Obsidiana
  │   └── color.tokens.spec.ts   // Tests específicos de marca
  └── ixiptla/
      ├── color.tokens.json      // Paleta de colores Ixiptla
      ├── design.tokens.json     // Sobrescrituras específicas de marca
      ├── font.tokens.json       // Tipografía personalizada
      └── *.spec.ts              // Tests comprehensivos de marca

Sistema de Construcción Dinámico con Style Dictionary: Reemplacé la configuración estática con un script de construcción JavaScript dinámico que genera salidas específicas por marca. El sistema combina tokens base con tokens específicos de marca durante el tiempo de construcción, creando paquetes de distribución aislados por marca.

Pipeline de Construcción Avanzado

import StyleDictionary from 'style-dictionary';

function getStyleDictionaryConfig(brand) {
  return {
    log: { verbosity: 'verbose' },
    source: [
      `src/tokens/brands/${brand}/*.json`,
      'src/tokens/base/**/*.json'  // Combinar tokens base
    ],
    platforms: {
      css: {
        transformGroup: 'css',
        buildPath: `dist/${brand}/css/`,
        files: [{ destination: '_variables.css', format: 'css/variables' }]
      },
      js: {
        transformGroup: 'js',
        buildPath: `dist/${brand}/`,
        files: [{ destination: 'index.js', format: 'javascript/es6' }]
      },
      ts: {
        transformGroup: 'js',
        buildPath: `dist/${brand}/`,
        files: [{
          destination: 'index.d.ts',
          format: 'typescript/es6-declarations',
          options: { outputLiteralTypes: true }
        }]
      }
    }
  };
}

// Generar salidas para cada marca
['obsidiana', 'ixiptla'].forEach(brand => {
  const sd = new StyleDictionary(getStyleDictionaryConfig(brand));
  sd.buildAllPlatforms();
});

Sistema Sofisticado de Exportación de Paquetes: Evolucioné desde exportaciones simples a importaciones complejas basadas en rutas soportando múltiples patrones de consumo. El paquete ahora soporta importaciones de marca predeterminada, importaciones de marca específica e importaciones solo CSS con resolución inteligente de rutas.

Exportaciones de Paquete Avanzadas

{
  "exports": {
    ".": {
      "types": "./dist/obsidiana/index.d.ts",
      "import": "./dist/obsidiana/index.js",
      "default": "./dist/obsidiana/index.js"
    },
    "./css": "./dist/obsidiana/css/_variables.css",
    "./*/css": "./dist/*/css/_variables.css",
    "./*": {
      "types": "./dist/*/index.d.ts",
      "import": "./dist/*/index.js",
      "default": "./dist/*/index.js"
    }
  }
}

Sistema de Validación Inter-Marca: Implementé testing comprehensivo que valida consistencia de estructura de tokens a través de marcas mientras permite variaciones específicas por marca. El sistema asegura que todas las marcas mantengan la misma jerarquía de tokens para interoperabilidad.

Testing de Consistencia de Marcas

describe('Consistencia de Tokens Multi-Marca', () => {
  const brands = ['obsidiana', 'ixiptla'];
  
  it('debe mantener estructura de tokens consistente entre marcas', () => {
    brands.forEach(brand => {
      const tokens = require(`./brands/${brand}/color.tokens.json`);
      
      // Validar consistencia estructural
      expect(tokens.color).toHaveProperty('primary');
      expect(tokens.color).toHaveProperty('base');
      
      // Validar completitud de temas
      Object.keys(tokens.color).forEach(category => {
        expect(tokens.color[category]).toHaveProperty('light');
        expect(tokens.color[category]).toHaveProperty('dark');
      });
    });
  });

  it('debe validar valores OKLCH en todas las marcas', () => {
    brands.forEach(brand => {
      const validateColorStructure = (obj: any) => {
        if (obj.value && obj.type === 'color') {
          expect(obj.value).toMatch(/^oklch\(\d+\.?\d*% \d+\.?\d* \d+\.?\d*\)$/);
        }
        Object.values(obj).forEach(value => {
          if (typeof value === 'object' && value !== null) {
            validateColorStructure(value);
          }
        });
      };
      
      const tokens = require(`./brands/${brand}/color.tokens.json`);
      validateColorStructure(tokens);
    });
  });
});

Evolución de Uso

Versión 1 (Marca Única)

// Importaciones simples de marca única
import { ColorPrimaryDefault } from '@codigo-obsidiana/design-tokens';

Versión 2 (Multi-Marca)

// Marca predeterminada (Obsidiana)
import { ColorPrimaryLightDefault } from '@codigo-obsidiana/design-tokens';

// Importaciones de marca específica
import { ColorPrimaryLightDefault as IxiptlaColorPrimary } 
  from '@codigo-obsidiana/design-tokens/ixiptla';

// Importaciones CSS por marca
import '@codigo-obsidiana/design-tokens/obsidiana/css';
import '@codigo-obsidiana/design-tokens/ixiptla/css';

// Cambio dinámico de marca
const getBrandTokens = async (brand: 'obsidiana' | 'ixiptla') => {
  return await import(`@codigo-obsidiana/design-tokens/${brand}`);
};

Diferenciación de Colores por Marca

Marca Obsidiana (Estética tech azul-púrpura):

{
  "primary": {
    "light": { "default": "oklch(72.6% 0.21 245)" },  // Azul rico
    "dark": { "default": "oklch(72.6% 0.21 245)" }
  }
}

Marca Ixiptla (Estética cálida tierra):

{
  "primary": {
    "light": { "default": "oklch(55% 0.15 40.24)" },   // Naranja-rojo cálido
    "dark": { "default": "oklch(65% 0.15 40.24)" }
  }
}

Resultados

Escalabilidad Mejorada: La arquitectura multimarca permite despliegue rápido de nuevas líneas de productos con estructura de tokens consistente pero identidad visual única, reduciendo tiempo al mercado para nuevas marcas en 70%.

Experiencia de Desarrollador Mejorada: Las importaciones basadas en rutas proporcionan selección intuitiva de marca mientras mantienen capacidades de tree-shaking. El soporte de TypeScript asegura validación en tiempo de compilación a través de todas las combinaciones de marca.

Experiencia Inter-Marca Consistente: Los tokens base compartidos aseguran espaciado consistente, escalas tipográficas y patrones de interacción mientras permiten personalización completa de paleta de colores por marca.

Optimización de Construcción Avanzada: La configuración dinámica de Style Dictionary genera bundles optimizados específicos por marca sin contaminación cruzada, reduciendo tamaños de bundle en 40% comparado con enfoques de paquete único.

Aseguramiento de Calidad Comprehensivo: El testing de validación inter-marca previene regresiones y asegura consistencia de estructura de tokens, capturando 95% de problemas potenciales de integración antes del despliegue.

Arquitectura A Prueba de Futuro: El sistema jerárquico de tokens y pipeline de construcción dinámico acomoda fácilmente nuevas marcas, variaciones de tema y categorías de tokens sin cambios arquitectónicos.