@datatechsolutions/tympan-tokens 0.3.0

package/src/dtcg.ts

@@ -0,0 +1,102 @@
+// Conversion between resolved themes and W3C Design Tokens Community Group
+// (DTCG, 2025.10 format) trees: colour objects with `colorSpace` and
+// `components`, dimension objects with `value` and `unit`.
+// Every generated token carries its CSS custom property name in
+// `$extensions["br.com.datatechsolutions.tympan"].cssName` so any DTCG tool maps it back exactly.
+
+import { toHex, type Rgba } from './color.ts'
+import { RAMP_STEPS, type Density, DENSITIES, type ResolvedTheme, type ShadowLayer } from './theme.ts'
+
+export interface DtcgColor {
+  colorSpace: 'srgb'
+  components: [number, number, number]
+  alpha?: number
+  hex: string
+}
+
+type Tree = { [key: string]: Tree | unknown }
+
+const r4 = (v: number) => Math.round(v * 10000) / 10000
+
+export function toDtcgColor(c: Rgba): DtcgColor {
+  const out: DtcgColor = { colorSpace: 'srgb', components: [r4(c.r), r4(c.g), r4(c.b)], hex: toHex(c) }
+  if (c.a < 1) out.alpha = r4(c.a)
+  return out
+}
+
+export function fromDtcgColor(v: DtcgColor | string): Rgba {
+  if (typeof v === 'string') {
+    const h = v.replace('#', '')
+    return { r: parseInt(h.slice(0, 2), 16) / 255, g: parseInt(h.slice(2, 4), 16) / 255, b: parseInt(h.slice(4, 6), 16) / 255, a: 1 }
+  }
+  const [r, g, b] = v.components
+  return { r, g, b, a: v.alpha ?? 1 }
+}
+
+const px = (value: number) => ({ value, unit: 'px' as const })
+const ext = (cssName: string) => ({ 'br.com.datatechsolutions.tympan': { cssName } })
+
+function shadowValue(layers: ShadowLayer[]) {
+  return layers.map((l) => ({
+    color: toDtcgColor(l.color),
+    offsetX: px(l.x),
+    offsetY: px(l.y),
+    blur: px(l.blur),
+    spread: px(l.spread),
+    ...(l.inset ? { inset: true } : {}),
+  }))
+}
+
+/** DTCG tree for one resolved theme and mode. */
+export function themeToDtcg(t: ResolvedTheme): Tree {
+  const color: Tree = { $type: 'color' }
+  for (const [name, c] of Object.entries(t.colors)) {
+    color[name] = { $value: toDtcgColor(c), $extensions: ext(`--ty-${name}`) }
+  }
+  const ramp: Tree = { $type: 'color' }
+  for (const [seed, steps] of Object.entries(t.ramps)) {
+    const group: Tree = {}
+    for (const step of RAMP_STEPS) group[String(step)] = { $value: toDtcgColor(steps[step]), $extensions: ext(`--ty-${seed}-${step}`) }
+    ramp[seed] = group
+  }
+  const shadow: Tree = { $type: 'shadow' }
+  for (const [name, layers] of Object.entries(t.shadows)) {
+    shadow[name] = { $value: shadowValue(layers), $extensions: ext(`--ty-shadow-${name}`) }
+  }
+  const dimension: Tree = { $type: 'dimension' }
+  for (const [name, v] of Object.entries(t.dimensions)) dimension[name] = { $value: px(v), $extensions: ext(`--ty-${name}`) }
+  const number: Tree = { $type: 'number' }
+  for (const [name, v] of Object.entries(t.numbers)) number[name] = { $value: v, $extensions: ext(`--ty-${name}`) }
+  
+  
+  const fontFamily: Tree = { $type: 'fontFamily' }
+  for (const [name, list] of Object.entries(t.fonts)) fontFamily[name] = { $value: [...list], $extensions: ext(`--ty-font-${name}`) }
+  return {
+    $description: `Theme ${t.name}, ${t.mode} mode, ${t.contrast} contrast. Generated by @datatechsolutions/tympan-tokens.`,
+    color,
+    ramp,
+    gradient: {
+      $type: 'gradient',
+      cta: {
+        $value: t.cta.stops.map((s, i, all) => ({ color: toDtcgColor(s), position: all.length === 1 ? 0 : r4(i / (all.length - 1)) })),
+        $extensions: { 'br.com.datatechsolutions.tympan': { cssName: '--ty-cta', angle: t.cta.angle } },
+      },
+    },
+    shadow,
+    dimension,
+    number,
+    ...(Object.keys(t.fonts).length ? { fontFamily } : {})
+  }
+}
+
+/** DTCG tree for one density step. */
+export function densityToDtcg(density: Density): Tree {
+  const group: Tree = { $type: 'dimension' }
+  for (const [k, v] of Object.entries(DENSITIES[density])) {
+    group[k] =
+      k === 'density'
+        ? { $type: 'number', $value: v, $extensions: ext(`--ty-${k}`) }
+        : { $value: px(v), $extensions: ext(`--ty-${k}`) }
+  }
+  return { $description: `Density ${density}.`, density: group }
+}

package/src/flow.ts

@@ -0,0 +1,130 @@
+// Canvas tokens (--ty-flow-*) for the flow canvas (@datatechsolutions/tympan/flow): kind tones, connectors,
+// node frame and state rings, the canvas plane, provenance band and research
+// step sizes, and data shape colours.
+//
+// Colour tokens are references to theme roles, emitted as `var(--ty-role)` so
+// every theme, mode, contrast level and forced-colours mapping follows without
+// a per-theme copy. In DTCG they are aliases (`{color.accent}`,
+// `{dimension.radius-card}`); a soft tint carries its mix in
+// `$extensions["br.com.datatechsolutions.tympan"].mix`. Sizes are plain px dimensions (the
+// provenance layout reads them at mount). No gradients: the design direction
+// reserves the gradient for the primary button.
+
+export type FlowToken =
+  | { type: 'color'; ref: string; mix?: number }
+  | { type: 'dimension'; ref: string }
+  | { type: 'dimension'; px: number }
+
+export const FLOW_TONES = [
+  'categorical-1', 'categorical-2', 'categorical-3', 'categorical-4',
+  'categorical-5', 'categorical-6', 'categorical-7', 'categorical-8', 'neutral',
+] as const
+export type FlowTone = (typeof FLOW_TONES)[number]
+
+/** Tint strength of a tone's soft variant (badge background). */
+const SOFT_MIX = 14
+
+const color = (ref: string, mix?: number): FlowToken => (mix === undefined ? { type: 'color', ref } : { type: 'color', ref, mix })
+const px = (value: number): FlowToken => ({ type: 'dimension', px: value })
+
+function toneTokens(): Array<[string, FlowToken]> {
+  const out: Array<[string, FlowToken]> = []
+  const cats = FLOW_TONES.filter((t) => t !== 'neutral')
+  // Full strength (bubble fill, port, overview map), ink on it, soft tint and text in the tone.
+  for (const t of cats) out.push([`tone-${t}`, color(t)])
+  out.push(['tone-neutral', color('ink-3')])
+  for (const t of cats) out.push([`tone-${t}-ink`, color('on-accent')])
+  out.push(['tone-neutral-ink', color('surface-solid')])
+  for (const t of cats) out.push([`tone-${t}-soft`, color(t, SOFT_MIX)])
+  out.push(['tone-neutral-soft', color('surface-sunken')])
+  for (const t of cats) out.push([`tone-${t}-text`, color(t)])
+  out.push(['tone-neutral-text', color('ink-2')])
+  return out
+}
+
+/** Every canvas token, in stylesheet order (name without the `--ty-flow-` prefix). */
+export const FLOW_TOKENS: ReadonlyArray<readonly [string, FlowToken]> = [
+  ...toneTokens(),
+  // Connectors. Rest uses the >=3:1 boundary role (WCAG 1.4.11), not line-strong.
+  ['connector', color('input')],
+  ['connector-active', color('accent')],
+  ['connector-true', color('success')],
+  ['connector-false', color('danger')],
+  ['connector-rule', color('categorical-2')],
+  ['connector-width', px(1.5)],
+  ['connector-width-active', px(2.5)],
+  // Node frame and state rings.
+  ['node-border', color('line-strong')],
+  ['node-border-hover', color('input')],
+  ['ring-selected', color('accent')],
+  ['ring-running', color('warning')],
+  ['ring-succeeded', color('success')],
+  ['ring-failed', color('danger')],
+  ['node-surface', color('surface-raised-solid')],
+  ['node-radius', { type: 'dimension', ref: 'radius-card' }],
+  // Canvas plane.
+  ['plane', color('surface-sunken')],
+  ['grid-dot', color('line-strong')],
+  ['guide', color('accent')],
+  ['marquee', color('accent-soft')],
+  // Provenance bands.
+  ['band', px(96)],
+  ['band-label', px(130)],
+  ['node-h', px(72)],
+  ['node-w', px(236)],
+  // Research steps and the data shapes on their ports (colour always paired with the shape word).
+  ['step-w', px(250)],
+  ['step-h', px(86)],
+  ['col-gap', px(56)],
+  ['shape-records', color('accent')],
+  ['shape-table', color('categorical-1')],
+  ['shape-number', color('warning')],
+  ['shape-chart', color('categorical-8')],
+  ['shape-decision', color('danger')],
+]
+
+export const flowCssName = (name: string) => `--ty-flow-${name}`
+
+/** CSS value of one canvas token. */
+export function flowTokenCss(token: FlowToken): string {
+  if ('px' in token) return `${token.px}px`
+  const ref = `var(--ty-${token.ref})`
+  return token.type === 'color' && token.mix !== undefined ? `color-mix(in oklab, ${ref} ${token.mix}%, transparent)` : ref
+}
+
+/** Ordered `[--ty-flow-name, value]` pairs (the generator's direct serialisation). */
+export function flowVariables(): Array<[string, string]> {
+  return FLOW_TOKENS.map(([name, token]) => [flowCssName(name), flowTokenCss(token)])
+}
+
+/** DTCG tree of the canvas tokens; colour and radius values alias the theme tree. */
+export function flowToDtcg(): Record<string, unknown> {
+  const flow: Record<string, unknown> = {}
+  for (const [name, token] of FLOW_TOKENS) {
+    const app: Record<string, unknown> = { cssName: flowCssName(name) }
+    let $value: unknown
+    if ('px' in token) $value = { value: token.px, unit: 'px' }
+    else if (token.type === 'color') {
+      $value = `{color.${token.ref}}`
+      if (token.mix !== undefined) app.mix = { space: 'oklab', amount: token.mix / 100, with: 'transparent' }
+    } else $value = `{dimension.${token.ref}}`
+    flow[name] = { $type: token.type, $value, $extensions: { 'br.com.datatechsolutions.tympan': app } }
+  }
+  return {
+    $description: 'Canvas tokens for the flow canvas (@datatechsolutions/tympan/flow). Colour values alias theme roles and are emitted as var() references. Generated by @datatechsolutions/tympan-tokens.',
+    flow,
+  }
+}
+
+/**
+ * The `[data-tone]` mapping: a tone name on any element selects its four parts
+ * as `--ty-flow-tone`, `-ink`, `-soft` and `-text`.
+ */
+export function flowToneRules(): string {
+  return FLOW_TONES.map(
+    (t) =>
+      `[data-tone="${t}"] {\n` +
+      ['', '-ink', '-soft', '-text'].map((part) => `  --ty-flow-tone${part}: var(--ty-flow-tone-${t}${part});`).join('\n') +
+      '\n}',
+  ).join('\n\n')
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+// @datatechsolutions/tympan-tokens: design tokens and the theme generator (FSL-1.1-ALv2).
+export * from './color.ts'
+export * from './theme.ts'
+export * from './presets.ts'
+export * from './dtcg.ts'
+export * from './stylesheet.ts'
+export * from './flow.ts'
+export * from './print-presets.ts'
+export * from './print-themes.ts'
+export * from './print-aliases.ts'
+
+import { presets as corePresets } from './presets.ts'
+import { printThemePresets } from './print-themes.ts'
+import type { ThemeConfig } from './theme.ts'
+
+// Unified exported themes: UI + Book themes combined
+export const allThemes: readonly ThemeConfig[] = [...corePresets, ...printThemePresets]

package/src/presets.ts

@@ -0,0 +1,135 @@
+import { seedFromColor, type Seed, type SeedName, type ThemeConfig } from './theme.ts'
+
+// Seeds. The brand hue comes from the design direction's accent (§2.3); the
+// neutral carries a slight tint of the brand hue; semantic hues are chosen so
+// the proof-state greens sit about 30 degrees away from the brand teal (§2.3).
+const brand = seedFromColor('#166e5a', 0.13)
+
+const baseSeeds: Record<SeedName, Seed> = {
+  brand,
+  neutral: { hue: brand.hue, chroma: 0.012 },
+  danger: { hue: 12, chroma: 0.2 },
+  warning: { hue: 68, chroma: 0.15 },
+  success: { hue: 148, chroma: 0.16 },
+  info: { hue: 255, chroma: 0.06 },
+}
+
+/**
+ * Default theme. Generated from seeds, with the exact colours of design
+ * direction §2.3 pinned so the product matches the approved direction.
+ */
+export const tympanPreset: ThemeConfig = {
+  name: 'tympan',
+  label: 'Tympan',
+  seeds: baseSeeds,
+  radius: 10,
+  contrast: 'default',
+  glass: true,
+  cta: 'gradient',
+  pins: {
+    light: {
+      brand: '#166e5a',
+      'focus-ring': '#166e5a',
+      'brand-strong': '#0f5a49',
+      'brand-soft': 'rgb(22 110 90 / 0.10)',
+      'on-brand': '#f6fbf9',
+      bg: '#f6f8fa',
+      surface: 'rgb(252 253 253 / 0.82)',
+      'surface-raised': 'rgb(252 253 253 / 0.94)',
+      'surface-solid': '#fcfdfd',
+      'surface-raised-solid': '#fcfdfd',
+      'surface-sunken': '#eef2f5',
+      line: 'rgb(100 116 139 / 0.22)',
+      'line-strong': 'rgb(100 116 139 / 0.38)',
+      ink: '#0f172a',
+      'ink-2': '#334155',
+      'ink-3': '#526077',
+      success: '#15803d',
+      warning: '#a16207',
+      danger: '#be123c',
+      neutral: '#526077',
+    },
+    dark: {
+      brand: '#34d399',
+      'focus-ring': '#34d399',
+      'brand-strong': '#6ee7b7',
+      'brand-soft': 'rgb(52 211 153 / 0.14)',
+      'on-brand': '#052e25',
+      bg: '#0a0f1c',
+      surface: 'rgb(20 28 46 / 0.72)',
+      'surface-raised': 'rgb(28 38 60 / 0.86)',
+      'surface-solid': '#141c2e',
+      'surface-raised-solid': '#1c263c',
+      'surface-sunken': '#0f1626',
+      line: 'rgb(148 163 184 / 0.16)',
+      'line-strong': 'rgb(148 163 184 / 0.30)',
+      ink: '#eef2f7',
+      'ink-2': '#cbd5e1',
+      'ink-3': '#94a3b8',
+      success: '#4ade80',
+      warning: '#fbbf24',
+      danger: '#fb7185',
+      neutral: '#94a3b8',
+    },
+  },
+  ctaPins: {
+    light: ['#047857', '#0f766e', '#0369a1'],
+    dark: ['#047857', '#0f766e', '#0369a1'],
+  },
+}
+
+/** Brand-free grey theme for embedding and white-label use. Fully generated. */
+export const neutralPreset: ThemeConfig = {
+  name: 'neutral',
+  label: 'Neutral',
+  seeds: {
+    brand: { hue: 255, chroma: 0.03 },
+    neutral: { hue: 255, chroma: 0.008 },
+    danger: { hue: 18, chroma: 0.19 },
+    warning: { hue: 70, chroma: 0.14 },
+    success: { hue: 150, chroma: 0.14 },
+    info: { hue: 255, chroma: 0.05 },
+  },
+  radius: 8,
+  contrast: 'default',
+  glass: true,
+  cta: 'solid',
+}
+
+/**
+ * The Fakhir research platform's look, selected by name
+ * (`data-ty-theme="fakhir"`). Today it carries the default theme's values; it
+ * is a separate preset so that app keeps its look if the default changes.
+ */
+export const fakhirPreset: ThemeConfig = {
+  ...tympanPreset,
+  name: 'fakhir',
+  label: 'Fakhir',
+}
+
+/** Default hues with high contrast, opaque surfaces and a thicker focus ring. */
+export const highContrastPreset: ThemeConfig = {
+  name: 'high-contrast',
+  label: 'High contrast',
+  seeds: baseSeeds,
+  radius: 10,
+  contrast: 'high',
+  glass: false,
+  cta: 'solid',
+}
+
+export const astrlabePreset: ThemeConfig = {
+  name: 'astrlabe',
+  label: 'Astrlabe',
+  seeds: {
+    ...baseSeeds,
+    brand: { hue: 240, chroma: 0.15 },
+  },
+  radius: 8,
+  contrast: 'default',
+  glass: true,
+  cta: 'solid',
+}
+
+export const presets: readonly ThemeConfig[] = [tympanPreset, fakhirPreset, neutralPreset, highContrastPreset, astrlabePreset]
+export const DEFAULT_THEME = 'tympan'

package/src/presets.ts.diff

@@ -0,0 +1,26 @@
+--- datatech/tympan-wt/site/packages/tokens/src/presets.ts
++++ datatech/tympan-wt/site/packages/tokens/src/presets.ts
+@@ -102,4 +102,23 @@
+-export const presets: readonly ThemeConfig[] = [tympanPreset, fakhirPreset, neutralPreset, highContrastPreset]
++export const astrlabePreset: ThemeConfig = {
++  name: 'astrlabe',
++  label: 'Astrlabe',
++  seeds: {
++    ...baseSeeds,
++    brand: { hue: 240, chroma: 0.15 }, // Example deep blue for Astrlabe
++  },
++  radius: 6,
++  contrast: 'comfortable',
++  glass: false,
++  cta: 'solid',
++  pins: {
++    light: {
++      brand: '#4f46e5',
++    },
++    dark: {
++      brand: '#6366f1',
++    }
++  }
++}
++
++export const presets: readonly ThemeConfig[] = [tympanPreset, fakhirPreset, neutralPreset, highContrastPreset, astrlabePreset]

package/src/print-aliases.ts

@@ -0,0 +1,84 @@
+// Deprecated ids of the print book styles and of their UI themes. Kept in a
+// module of its own, with no runtime imports, so that hosts which only need to
+// resolve a stored theme name (ThemeProvider, themeInitScript) can import it
+// from `@datatechsolutions/tympan-tokens/print-aliases` without loading the
+// presets or generating the print themes.
+
+import type { PrintPresetName } from './print-presets.ts'
+
+/** Prefix of every print theme name: `data-ty-theme="print-<style>"`. */
+export const PRINT_THEME_PREFIX = 'print-'
+
+/**
+ * Deprecated style ids and the current id each one maps to. The styles were
+ * renamed to neutral, descriptive ids (no trademarks, institutions or people's
+ * names); the old ids keep working through `resolvePrintStyleName`,
+ * `resolvePrintStyle`, `LivroPrint estilo` and, as `print-<old id>`, the UI
+ * theme lookup (`resolvePrintThemeName`), with a one-time console warning in
+ * development builds.
+ *
+ * Removal: the aliases (and the `'modulor'` emblem) will be dropped in the
+ * next major version of @datatechsolutions/tympan-tokens and
+ * @datatechsolutions/tympan-print; migrate stored data books to the new ids.
+ */
+export const PRINT_STYLE_ALIASES = {
+  economist: 'semanario',
+  ft: 'papel-salmao',
+  schiphol: 'sinalizacao',
+  'jornal-do-brasil': 'jornal-1959',
+  'atlas-ibge': 'atlas-oficial',
+  deardata: 'cartao-postal',
+  tufte: 'minimo-de-tinta',
+  holmes: 'infografico-ilustrado',
+  bayer: 'diagrama-modernista',
+  dubois: 'graficos-1900',
+  minard: 'fluxo-historico',
+  mccandless: 'blocos-coloridos',
+  corbusier: 'proporcao-modular',
+  aicher: 'pictogramas',
+  vignelli: 'mapa-de-metro',
+  'athos-bulcao': 'azulejo-modernista',
+  crouwel: 'grade-holandesa',
+  'saul-bass': 'papel-recortado',
+} as const satisfies Record<string, PrintPresetName>
+
+/** A deprecated style id (see PRINT_STYLE_ALIASES). */
+export type PrintStyleAlias = keyof typeof PRINT_STYLE_ALIASES
+
+const isDev = (() => {
+  try {
+    return (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env?.NODE_ENV !== 'production'
+  } catch {
+    return true
+  }
+})()
+const warned = new Set<string>()
+
+/** Warns once per id (development builds only) that a deprecated id was used. @internal */
+export function warnDeprecatedPrintId(old: string, current: string, kind = 'print style'): void {
+  if (!isDev || warned.has(old)) return
+  warned.add(old)
+  console.warn(`[@datatechsolutions/tympan] The ${kind} "${old}" is deprecated; use "${current}". The old id will be removed in the next major version.`)
+}
+
+/**
+ * Deprecated print theme names (`print-<old style id>`) and the current theme
+ * each maps to, derived from PRINT_STYLE_ALIASES (for example
+ * `print-economist` -> `print-semanario`). Same removal schedule: dropped in
+ * the next major version.
+ */
+export const PRINT_THEME_ALIASES: Readonly<Record<string, string>> = Object.fromEntries(
+  Object.entries(PRINT_STYLE_ALIASES).map(([old, current]) => [`${PRINT_THEME_PREFIX}${old}`, `${PRINT_THEME_PREFIX}${current}`]),
+)
+
+/**
+ * The current name of a theme: a deprecated `print-<old id>` is mapped to its
+ * `print-<new id>` (with a one-time development warning); any other name is
+ * returned unchanged.
+ */
+export function resolvePrintThemeName(theme: string): string {
+  if (!Object.hasOwn(PRINT_THEME_ALIASES, theme)) return theme
+  const current = PRINT_THEME_ALIASES[theme]!
+  warnDeprecatedPrintId(theme, current, 'theme')
+  return current
+}