@studiolxd/brand 38.12.4

package/src/tokens/tokens.ts

@@ -0,0 +1,59 @@
+/*
+ * Los tokens del sistema, legibles desde JS/TS.
+ *
+ * `tokens.json` lo genera `pnpm build:tokens` (plataforma `js` de
+ * `sd.config.mjs`) en la misma pasada de transformación que el CSS, así que
+ * cada valor es literalmente el que emite el `:root` generado. No editarlo a
+ * mano.
+ *
+ * Para qué: hay consumidores que no pueden leer una custom property. Un correo
+ * HTML es el caso claro —Outlook no resuelve `var()`, así que todo estilo va
+ * inline y resuelto en tiempo de render—, pero vale igual para un canvas, un
+ * PDF o cualquier sitio donde el valor haga falta como dato y no como CSS.
+ *
+ * Lo que NO hay aquí son los pares oscuros: un token `surface-dark-*` se
+ * publica con el nombre de su par claro, así que no puede convivir con él en
+ * un mapa plano. Quien necesite los dos temas (el correo) los deriva de los
+ * roles semánticos `*-on-dark`, que sí son tokens normales — la misma regla de
+ * derivación que documentan Foundations y el CLAUDE.md.
+ */
+import raw from './tokens.json';
+
+/** Nombre de una custom property del sistema, con sus dos guiones. */
+export type TokenName = string;
+
+/**
+ * Todos los tokens del sistema, `{ '--nombre': 'valor' }`, con los valores ya
+ * resueltos (nunca un `var()`).
+ */
+export const tokens: Readonly<Record<TokenName, string>> = raw;
+
+/**
+ * El valor de un token, o un error si no existe.
+ *
+ * Falla en vez de devolver `undefined` a propósito: un estilo inline con un
+ * valor vacío no se ve roto, se ve «casi bien», y ese fallo viaja hasta la
+ * bandeja de entrada de alguien.
+ */
+export function token(name: TokenName): string {
+  const value = tokens[name];
+  if (value === undefined) throw new Error(`Token desconocido: ${name}`);
+  return value;
+}
+
+/** 1rem, en píxeles: el sistema no toca el `font-size` del `html`. */
+const ROOT_FONT_SIZE = 16;
+
+/**
+ * El valor de un token en píxeles absolutos.
+ *
+ * La escala del sistema está en `rem`, que fuera del navegador no significa
+ * nada: Outlook resuelve `rem` contra su propio contexto y el correo sale con
+ * otro tamaño. Los tokens que ya vienen en `px` (radios, grosores de borde) y
+ * los sin unidad (interlineados, pesos) pasan tal cual.
+ */
+export function tokenPx(name: TokenName): string {
+  const value = token(name);
+  const rem = value.match(/^(-?[\d.]+)rem$/);
+  return rem ? `${Number(rem[1]) * ROOT_FONT_SIZE}px` : value;
+}

package/src/tokens/typography.ts

@@ -0,0 +1,91 @@
+/*
+ * Datos de la página de Tipografía. Todo sale de los JSON de tokens.
+ */
+import family from '../../tokens/typography/family.json';
+import size from '../../tokens/typography/size.json';
+import weight from '../../tokens/typography/weight.json';
+import lineHeight from '../../tokens/typography/line-height.json';
+import letterSpacing from '../../tokens/typography/letter-spacing.json';
+import content from '../../tokens/size/content.json';
+import text from '../../tokens/component/text.json';
+import { flattenTokens, resolveRef } from './utils';
+
+type TokenEntry = { $value: string; $type: string; $description?: string };
+type Group = Record<string, TokenEntry>;
+
+export const familyTokens = flattenTokens(family as never);
+export const sizeTokens = flattenTokens(size as never);
+export const lineHeightTokens = flattenTokens(lineHeight as never);
+export const letterSpacingTokens = flattenTokens(letterSpacing as never);
+export const measureTokens = flattenTokens(content as never);
+
+/* ---- Pesos: la escala de la fuente y los dos roles que usa el sistema ---- */
+const allWeights = flattenTokens(weight as never);
+export const weightRoleTokens  = allWeights.filter((t) => /--font-weight-(default|emphasis)$/.test(t.name));
+export const weightScaleTokens = allWeights.filter((t) => !/--font-weight-(default|emphasis)$/.test(t.name));
+
+/* ---- Familias ---- */
+type FontExtensions = { 'studio-lxd': { intro: string; link: string } };
+type FontToken = { $value: string; $description?: string; $extensions: FontExtensions };
+
+export const fontFamilies = Object.entries(family['font-family'] as Record<string, FontToken>).map(([key, token]) => ({
+  key,
+  name: token.$value.split(',')[0].trim().replace(/['"]/g, ''),
+  fontFamily: token.$value,
+  intro: token.$extensions['studio-lxd'].intro,
+  link: token.$extensions['studio-lxd'].link,
+}));
+
+/* ---- Estilos compuestos (text.json) resueltos a valores ---- */
+const entries = (group: Group, prefix: string) =>
+  Object.fromEntries(Object.entries(group).map(([k, v]) => [`${prefix}.${k}`, v.$value]));
+
+const refMap: Record<string, string> = {
+  ...entries(family['font-family'] as Group, 'font-family'),
+  ...entries(size['font-size'] as Group, 'font-size'),
+  ...entries(weight['font-weight'] as Group, 'font-weight'),
+  ...entries(lineHeight['line-height'] as Group, 'line-height'),
+  ...entries(letterSpacing['letter-spacing'] as Group, 'letter-spacing'),
+};
+// text.* se referencia a sí mismo (h1.font-family → text.heading.font-family): aplanar
+const walk = (tree: Record<string, unknown>, path: string[]) => {
+  for (const [k, v] of Object.entries(tree)) {
+    if (v && typeof v === 'object' && '$value' in (v as object)) refMap[[...path, k].join('.')] = (v as TokenEntry).$value;
+    else if (v && typeof v === 'object') walk(v as Record<string, unknown>, [...path, k]);
+  }
+};
+walk(text as Record<string, unknown>, []);
+const resolve = (ref: string) => resolveRef(ref, refMap);
+
+export interface TextStyle {
+  name: string;
+  /** Prefijo de las custom properties: --text-h1-*, --text-paragraph-* … */
+  cssPrefix: string;
+  size: string; weight: string; lineHeight: string; letterSpacing: string;
+  sizeRef: string; weightRef: string; lineHeightRef: string; letterSpacingRef: string;
+}
+
+const t = text.text as unknown as Record<string, Record<string, TokenEntry> | TokenEntry>;
+const style = (name: string, path: string, node: Record<string, TokenEntry>): TextStyle => ({
+  name,
+  cssPrefix: path ? `--text-${path}` : '--text',
+  size: resolve(node['font-size'].$value),
+  weight: resolve(node['font-weight'].$value),
+  lineHeight: resolve(node['line-height'].$value),
+  letterSpacing: resolve(node['letter-spacing'].$value),
+  sizeRef: node['font-size'].$value,
+  weightRef: node['font-weight'].$value,
+  lineHeightRef: node['line-height'].$value,
+  letterSpacingRef: node['letter-spacing'].$value,
+});
+
+// El párrafo no tiene nodo propio: es el cuerpo del lienzo (`text.*`), y las
+// variantes solo le pisan tamaño e interlineado.
+const base = t as unknown as Record<string, TokenEntry>;
+const para = t.paragraph as unknown as Record<string, Record<string, TokenEntry>>;
+export const textStyles: TextStyle[] = [
+  ...(['h1', 'h2', 'h3', 'h4', 'h5', 'h6'] as const).map((h) => style(h.toUpperCase(), h, t[h] as Record<string, TokenEntry>)),
+  style('Párrafo', '', base),
+  style('Párrafo grande', 'paragraph-large', { ...base, ...para.large }),
+  style('Párrafo pequeño', 'paragraph-small', { ...base, ...para.small }),
+];

package/src/tokens/utils.test.ts

@@ -0,0 +1,86 @@
+import { describe, it, expect } from 'vitest';
+import { resolveRef, flattenTokens } from './utils';
+
+describe('resolveRef', () => {
+  it('returns the value unchanged when it is not a reference', () => {
+    expect(resolveRef('#ffffff', {})).toBe('#ffffff');
+    expect(resolveRef('16px', {})).toBe('16px');
+    expect(resolveRef('solid', {})).toBe('solid');
+  });
+
+  it('resolves a direct reference', () => {
+    const map = { 'color.prussian': '#111e30' };
+    expect(resolveRef('{color.prussian}', map)).toBe('#111e30');
+  });
+
+  it('resolves chained references', () => {
+    const map = {
+      'color.primary': '{color.prussian}',
+      'color.prussian': '#111e30',
+    };
+    expect(resolveRef('{color.primary}', map)).toBe('#111e30');
+  });
+
+  it('returns the original ref when the key is not in the map', () => {
+    expect(resolveRef('{color.unknown}', {})).toBe('{color.unknown}');
+  });
+
+  it('stops when the resolved value equals the current value (circular guard)', () => {
+    const map = { 'color.loop': '{color.loop}' };
+    expect(resolveRef('{color.loop}', map)).toBe('{color.loop}');
+  });
+});
+
+describe('flattenTokens', () => {
+  it('flattens a single-level tree', () => {
+    const tree = {
+      white: { $value: '#ffffff', $type: 'color', $description: 'Pure white' },
+    };
+    expect(flattenTokens(tree)).toEqual([
+      { name: '--white', value: '#ffffff', description: 'Pure white' },
+    ]);
+  });
+
+  it('flattens a nested tree using dash-separated paths', () => {
+    const tree = {
+      color: {
+        text: {
+          'on-light': { $value: '#111e30', $type: 'color' },
+        },
+      },
+    };
+    expect(flattenTokens(tree)).toEqual([
+      { name: '--color-text-on-light', value: '#111e30', description: undefined },
+    ]);
+  });
+
+  it('prepends a prefix when provided', () => {
+    const tree = {
+      sm: { $value: '4px', $type: 'dimension' },
+    };
+    expect(flattenTokens(tree, 'spacing')).toEqual([
+      { name: '--spacing-sm', value: '4px', description: undefined },
+    ]);
+  });
+
+  it('handles multiple sibling tokens', () => {
+    const tree = {
+      sans: { $value: 'Inter, sans-serif', $type: 'string' },
+      mono: { $value: 'Fira Code, monospace', $type: 'string' },
+    };
+    const result = flattenTokens(tree);
+    expect(result).toHaveLength(2);
+    expect(result[0].name).toBe('--sans');
+    expect(result[1].name).toBe('--mono');
+  });
+
+  it('includes description when present and omits it when absent', () => {
+    const tree = {
+      a: { $value: '1', $type: 'number', $description: 'Token A' },
+      b: { $value: '2', $type: 'number' },
+    };
+    const [a, b] = flattenTokens(tree);
+    expect(a.description).toBe('Token A');
+    expect(b.description).toBeUndefined();
+  });
+});

package/src/tokens/utils.ts

@@ -0,0 +1,37 @@
+export interface Token {
+  name: string;
+  value: string;
+  description?: string;
+}
+
+type DtcgNode = { $value: string; $type: string; $description?: string };
+type DtcgTree = { [key: string]: DtcgNode | DtcgTree };
+
+/** Resolve a DTCG reference like "{color.prussian}" using a flat key→value map. */
+export function resolveRef(value: string, refMap: Record<string, string>): string {
+  let current = value;
+
+  while (true) {
+    const match = current.match(/^\{(.+)\}$/);
+    if (!match) return current;
+
+    const next = match[1] !== undefined ? refMap[match[1]] : undefined;
+    if (!next || next === current) return current;
+
+    current = next;
+  }
+}
+
+export function flattenTokens(tree: DtcgTree, prefix = ''): Token[] {
+  return Object.entries(tree).flatMap(([key, node]) => {
+    const path = prefix ? `${prefix}-${key}` : key;
+    if ('$value' in node) {
+      return [{
+        name: `--${path}`,
+        value: (node as DtcgNode).$value,
+        description: (node as DtcgNode).$description,
+      }];
+    }
+    return flattenTokens(node as DtcgTree, path);
+  });
+}