@datatechsolutions/tympan-tokens 0.3.0

package/LICENSE

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 Natalia Mesquita
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License.
+
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed
+under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+CONDITIONS OF ANY KIND, either express or implied. See the License for the
+specific language governing permissions and limitations under the License.

package/README.md

@@ -0,0 +1,318 @@
+# @datatechsolutions/tympan-tokens
+
+Design tokens and theme generator of Tympan, an Astrlabe-family component
+published by Datatech. Licence:
+FSL-1.1-ALv2 (Functional Source License, Version 1.1, Apache 2.0 Future
+License); see `LICENSE`.
+Visual source of truth: `docs/infra/design-direction-fakhir.md` (§2.1 to §2.13)
+in the thesis repository.
+
+```sh
+npm run build -w @datatechsolutions/tympan-tokens      # dist/tokens.css, tokens.json, values.js, dtcg/, contrast-report.md, index.js
+npm run typecheck -w @datatechsolutions/tympan-tokens  # tsc + source validation + WCAG gate
+npm test -w @datatechsolutions/tympan-tokens           # vitest: colour math, ramps, AA in every preset/mode, DTCG, stylesheet
+```
+
+## What is in the box
+
+| Output | Content |
+|---|---|
+| `@datatechsolutions/tympan-tokens/tokens.css` | every `--ty-*` custom property, in `@layer tympan.tokens` |
+| `@datatechsolutions/tympan-tokens/tokens.json` | resolved values: base, density steps, each preset × mode (× high contrast) |
+| `@datatechsolutions/tympan-tokens/dtcg/*.tokens.json` | W3C DTCG trees (2025.10 format) of every set, as fed to Style Dictionary (`dtcg/print/` for the print themes) |
+| `@datatechsolutions/tympan-tokens/print-themes.css` | opt-in: every print book style as a UI theme (`data-ty-theme="print-<style>"`), light, dark and high contrast |
+| `@datatechsolutions/tympan-tokens/print-themes/<theme>.css` | opt-in: one print theme per file (for example `print-themes/print-suico.css`) |
+| `@datatechsolutions/tympan-tokens/print-themes.json` | name, label, font stylesheet URL and CSS file of each print theme |
+| `@datatechsolutions/tympan-tokens/values` | the resolved values as a typed JS module (`values`, `cssVar()`) |
+| `@datatechsolutions/tympan-tokens` | the generator: colour math, `resolveTheme`, presets, `generateThemeCss`, DTCG conversion |
+| `dist/contrast-report.md` | WCAG ratio and APCA Lc of every declared pair, per preset and mode |
+
+## Token model
+
+**Static (authored as DTCG in `src/base/`)**: spacing on a 4 px base
+(`--ty-space-1..9`, §2.1), layout sizes (`--ty-layout-*`, §2.8), the 44 px
+touch target (`--ty-control-target`), type families, sizes with paired line
+heights, weights and tracking (§2.2), prose measures, durations and easings
+(`--ty-dur-*`, `--ty-ease`, `--ty-ease-out`, §2.7), stacking order (`--ty-z-*`).
+
+**Generated per theme and mode (`src/theme.ts`)**:
+
+- **Ramps**: 11 steps (`50 … 950`) per seed, computed in OKLCH:
+  `--ty-brand-*`, `--ty-neutral-*`, `--ty-danger-*`, `--ty-warning-*`,
+  `--ty-success-*`, `--ty-info-*`.
+- **Paired roles** (X / on-X):
+  `bg`/`on-bg`, `surface`/`on-surface`, `surface-raised`/`on-surface-raised`,
+  `surface-sunken`/`on-surface-sunken`, `brand`/`on-brand`,
+  `brand-soft`/`on-brand-soft`, `cta`/`on-cta`, `secondary`/`on-secondary`,
+  and for each tone `danger|warning|success|info|neutral`: `X`, `on-X`,
+  `X-soft`, `on-X-soft`. Also `ink`, `ink-2`, `ink-3` (three text levels),
+  `line`, `line-soft`, `line-strong`, `input` (field border, 3:1),
+  `focus-ring`, `focus-width`, `backdrop`, `ambient-1/2`.
+- **Proof states and actors** (§2.11): `proof-{proved,pending,refuted,not-disclosed,none}`
+  (+ `-soft`), `actor-{person,agent,system}` (+ `-soft`).
+- **Charts**: `chart-1..8` (aliases `categorical-1..8`), each ≥ 3:1 on the sheet.
+- **Navigation**: `nav-bg`, `on-nav`, `nav-active`, `on-nav-active`, `nav-line`.
+- **Radius**: one base `--ty-radius`; `radius-control` = base, `radius-card` =
+  1.6 × base, `radius-sheet` = 2.4 × base, `radius-pill`, `radius-agent` = 0.6 × base
+  (base 10 gives 10 / 16 / 24 / 6, §2.4).
+- **Elevation and glass**: `shadow-{sheet,raised,floating,modal,sheet-inset}`
+  tinted with the neutral hue (never black), `glass-blur-sheet`,
+  `glass-blur-floating`, `glass-saturate` (§2.5).
+- **Design-direction aliases**: `accent`, `accent-strong`, `accent-soft`,
+  `accent-ink`, `on-accent`, `on-accent-soft` point at the brand roles.
+- **Typography (optional)**: a theme with `fonts` sets `--ty-font-serif`
+  (role `display`: headings h1 to h3 and KPI numbers), `--ty-font-sans`
+  (role `body`) and `--ty-font-mono` (role `mono`) on its scope; the built-in
+  presets leave them to the base tokens. `elevation` (`soft` | `flat` |
+  `offset`) picks blurred shadows, none, or a hard ink shadow.
+
+**Density** (`data-ty-density`): `compact | default | comfortable` sets
+`--ty-control-height`, `--ty-control-height-touch`, `--ty-control-height-compact`
+and `--ty-density`. The 44 px hit area never changes.
+
+**Canvas component tokens (`src/flow.ts`, `--ty-flow-*`)**, used by the
+flow canvas (`@datatechsolutions/tympan/flow`): kind tones `tone-{categorical-1..8,neutral}` with
+`-ink`, `-soft` (a 14 % oklab mix) and `-text`, and the `[data-tone]` mapping
+that sets `--ty-flow-tone`, `-ink`, `-soft`, `-text` on any element;
+connectors (`connector`, `-active`, `-true`, `-false`, `-rule`, `-width`,
+`-width-active`); node frame (`node-border`, `-border-hover`, `-surface`,
+`-radius`) and state rings (`ring-{selected,running,succeeded,failed}`);
+canvas plane (`plane`, `grid-dot`, `guide`, `marquee`); provenance bands
+(`band` 96, `band-label` 130, `node-h` 72, `node-w` 236 px); research steps
+(`step-w` 250, `step-h` 86, `col-gap` 56 px) and data shapes
+(`shape-{records,table,number,chart,decision}`). Colours are DTCG aliases of
+theme roles (`dist/dtcg/flow.tokens.json`) emitted as `var(--ty-role)`, and are
+declared on every theme and mode scope so a nested theme re-resolves them.
+
+## Theming attributes
+
+```html
+<html data-ty-theme="tympan" data-ty-mode="system" data-ty-density="default">
+```
+
+- `data-ty-theme`: `tympan` (default, also applied to `:root`), `fakhir`,
+  `neutral`, `high-contrast`, or the name of a generated theme.
+- `data-ty-mode`: `light`, `dark`, or `system`/absent (follows `prefers-color-scheme`).
+- `data-ty-density`: see above.
+
+The attributes may be on the same element or nested (a light preview inside a
+dark page works). User preferences are handled in the stylesheet:
+
+| Preference | Effect |
+|---|---|
+| `prefers-color-scheme: dark` | dark values when the mode is `system` |
+| `prefers-contrast: more` | the high-contrast variant of the current theme |
+| `prefers-reduced-transparency: reduce` (and no `backdrop-filter` support) | opaque surfaces, no blur, no ambient |
+| `prefers-reduced-motion: reduce` | every `--ty-dur-*` becomes `0ms` |
+| `forced-colors: active` | roles map to system colours (`Canvas`, `CanvasText`, `Highlight`, …); shadows off |
+
+In the design system, `<ThemeProvider>` / `useTheme()` set these attributes and
+`themeInitScript()` applies the stored choice before first paint.
+
+## Presets
+
+| Preset | Seeds | Radius | Contrast | Glass | CTA |
+|---|---|---|---|---|---|
+| `tympan` (default) | brand teal from the §2.3 accent, neutral with a slight teal tint, semantic hues | 10 | default | on | gradient |
+| `fakhir` | the look of the Fakhir research platform; today the same values as `tympan` | 10 | default | on | gradient |
+| `neutral` | grey-blue brand, near-grey neutral | 8 | default | on | solid |
+| `high-contrast` | tympan seeds | 10 | high | off | solid |
+
+The `tympan` preset (and `fakhir`, which an app selects by name with
+`data-ty-theme="fakhir"` or `ThemeProvider theme="fakhir"`) **pins** the exact
+colours of design direction §2.3 (accent,
+surfaces, ink, lines, semantic tones, the CTA gradient) on top of the generated
+roles, so the product keeps the approved look; every other role is generated.
+`neutral` and `high-contrast` are fully generated.
+
+## Book-style print presets
+
+`printPresets` holds the 39 book diagramming styles used by
+`@datatechsolutions/tympan-print` (`PRINT_PRESET_NAMES` gives the order:
+`dashboard` … `papel-salmao`, then `dados-br`, `fluxo-historico`,
+`blocos-coloridos`, `construtivismo`, `bauhaus`, `brutalista`, `divulgacao`,
+`proporcao-modular`, `sinalizacao`, `pictogramas`, `mapa-de-metro`,
+`jornal-1959`, `azulejo-modernista`, `tropicalia`, `atlas-oficial`,
+`grade-holandesa`, `papel-recortado`, `pop-art`, `cientifico`, `art-nouveau`,
+`memphis`). Ids and labels are neutral, descriptive names; the tradition a
+style draws on is named only in its description (`referencia`, "inspirado em
+…").
+Optional fields cover page ornaments (`estrutura.moldura`, `cor.ornamento`),
+columns (`estrutura.barras`), running-head bands and title treatments. Each `PrintStyle` names its fonts (Google Fonts,
+OFL), paper and ink, data and proof-state colours, paper texture, stroke,
+chart renderer, proof-mark shape and page structure.
+
+```ts
+import { printPresets, printStyleToCss, googleFontsUrl } from '@datatechsolutions/tympan-tokens'
+
+printStyleToCss(printPresets.jornal)                       // [data-ty-print-style="jornal"] { --ty-print-*: … }
+printStyleToCss(printPresets.jornal, { pb: true })          // black and white: greys of equal luminance + the style's pb
+printStyleToCss(printPresets.jornal, { overrides: { cor: { destaque: '#8a1c7c' } } })
+```
+
+### Renamed styles (deprecated ids)
+
+Eighteen styles were renamed so that no id or label uses a trademark, an
+institution or a person's name. The old ids still work: `PRINT_STYLE_ALIASES`
+maps each one to its new id, and `resolvePrintStyleName`, `printPresetById`,
+`resolvePrintStyle` (which also takes an id), `LivroPrint estilo` and the UI
+theme lookup (`print-<old id>`, through `PRINT_THEME_ALIASES` and
+`resolvePrintThemeName`, used by `ThemeProvider` and `themeInitScript`) accept
+them, with a one-time console warning in development builds. The alias maps
+and resolvers are also published alone, without the presets, as
+`@datatechsolutions/tympan-tokens/print-aliases`.
+
+| Old id | New id | Label |
+| --- | --- | --- |
+| `economist` | `semanario` | Semanário de economia |
+| `ft` | `papel-salmao` | Papel salmão |
+| `schiphol` | `sinalizacao` | Sinalização de aeroporto |
+| `jornal-do-brasil` | `jornal-1959` | Jornal modernista (1959) |
+| `atlas-ibge` | `atlas-oficial` | Atlas oficial (cartografia) |
+| `deardata` | `cartao-postal` | Cartão-postal desenhado à mão |
+| `tufte` | `minimo-de-tinta` | Mínimo de tinta |
+| `holmes` | `infografico-ilustrado` | Infográfico ilustrado |
+| `bayer` | `diagrama-modernista` | Diagrama modernista |
+| `dubois` | `graficos-1900` | Gráficos de exposição (1900) |
+| `minard` | `fluxo-historico` | Fluxo histórico (séc. XIX) |
+| `mccandless` | `blocos-coloridos` | Blocos coloridos |
+| `corbusier` | `proporcao-modular` | Proporção modular |
+| `aicher` | `pictogramas` | Pictogramas esportivos |
+| `vignelli` | `mapa-de-metro` | Mapa de metrô |
+| `athos-bulcao` | `azulejo-modernista` | Azulejo modernista |
+| `crouwel` | `grade-holandesa` | Grade holandesa |
+| `saul-bass` | `papel-recortado` | Papel recortado |
+
+The labels of `tropicalia`, `pop-art`, `art-nouveau` and `memphis` no longer
+carry a person's name (the ids are unchanged), and the emblem `'modulor'` is
+now `'figura-modular'` (the old value is still drawn).
+
+**Removal:** the aliases, the `print-<old id>` theme names and the `'modulor'`
+emblem will be removed in the next major version of
+`@datatechsolutions/tympan-tokens` and `@datatechsolutions/tympan-print`.
+Migrate stored data books to the new ids before then.
+
+```ts
+resolvePrintStyle('economist').name   // 'semanario' (warns once in development)
+resolvePrintThemeName('print-tufte')  // 'print-minimo-de-tinta'
+```
+
+Tests hold every preset to WCAG AA for `tinta`, `tinta2` and the six proof
+colours on the paper (in colour and in P&B) and keep every data colour
+(`destaque`, `destaque2`, `contexto`, proof states) at CIEDE2000 ΔE ≥ 10 from
+the colours of the lakebrasil logo. `deltaE2000` and `rgbToLab` are exported
+from the colour module.
+
+## Print styles as UI themes
+
+`printStyleToTheme(style)` derives a `ThemeConfig` from any `PrintStyle`, and
+`printThemePresets` holds one per book style, named `print-<style>` (for
+example `print-suico`, `print-minimo-de-tinta`). The mapping is data-driven:
+
+- **Palette**: in the style's own mode (light for paper styles, dark for
+  dark-paper styles such as `prancheta`) the paper is `bg`, surfaces step
+  lighter than it and the well darker, `tinta`/`tinta2`/`tinta3` are the three
+  ink levels, the printed rule gives the lines, the highlighter tint is
+  `brand-soft` and the selected nav item, and the proof-state colours are the
+  danger, success and warning tones where they are chromatic. The brand is the
+  style's accent (`printStyleAccent`), moved along OKLCH lightness only as far
+  as it needs to read on the paper (`legibleOn`). Chart hues come from the
+  accents, ornaments and proof colours.
+- **Other mode**: generated from the same hues (neutral from the paper tint,
+  brand from the accent), with the paper colour as the ink and the printed
+  accent kept as the brand where it reads.
+- **Typography**: `fonts.display` and `fonts.body` are the style's title and
+  body stacks; `fonts.mono` is the style's mono stack only when it is really
+  monospace (otherwise the base mono stays). `fontsUrl` is the style's Google
+  Fonts css2 URL (`googleFontsUrl`) limited to those families.
+- **Surface**: radius from the print corner radius (mm at 96 dpi); glass,
+  a gradient call to action and soft shadows only for the card and wash
+  styles (`dashboard`, `aquarela`); flat shadows for the ruled print styles
+  (`suico`, `minimo-de-tinta`, `bauhaus` …); a hard offset shadow for cut-paper and
+  poster styles (`brutalista`, `memphis`, `pop-art`, `divulgacao`).
+- **Contrast**: every exact print colour is a pin only while all WCAG 2.2 AA
+  pairs hold in that mode; a pin that fails is dropped and the role is
+  regenerated from the style's hue (`printThemeDroppedPins(style)` lists
+  them). Tests run every pair of every print theme in light, dark and high
+  contrast.
+- **Overrides**: `printStyleToTheme(style, { brand, radius, glass, cta, elevation, pins })`,
+  and `PRINT_THEME_OVERRIDES` for judgements the data cannot express.
+
+The print themes are **not** in `tokens.css`. To enable them in an app:
+
+```ts
+import '@datatechsolutions/tympan/styles.css'                      // or tokens.css
+import '@datatechsolutions/tympan-tokens/print-themes.css'         // all print themes (about 2 MB, 160 kB gzip)
+// or only the ones you offer:
+import '@datatechsolutions/tympan-tokens/print-themes/print-suico.css'
+
+import { printThemeFontUrls } from '@datatechsolutions/tympan-tokens'
+<ThemeProvider theme="print-suico" fonts={printThemeFontUrls}>…</ThemeProvider>
+```
+
+`ThemeProvider`'s `fonts` map (theme name to stylesheet URL) adds the font
+link of the current theme; `themeInitScript(key, defaults, { fonts })` does the
+same before first paint. Without it the stacks fall back to the style's
+system families. `generatePrintThemesCss(list)` builds the same sheet at
+runtime. A default theme nested inside a print theme inherits the print
+fonts, because the built-in presets do not redeclare the font tokens.
+
+## Generator API
+
+```ts
+import { resolveTheme, generateThemeCss, themeToDtcg, tympanPreset, type ThemeConfig } from '@datatechsolutions/tympan-tokens'
+
+const config: ThemeConfig = {
+  name: 'lab',
+  seeds: {
+    brand: { hue: 200, chroma: 0.14 }, neutral: { hue: 200, chroma: 0.012 },
+    danger: { hue: 15, chroma: 0.2 }, warning: { hue: 70, chroma: 0.15 },
+    success: { hue: 150, chroma: 0.16 }, info: { hue: 250, chroma: 0.07 },
+  },
+  radius: 12, contrast: 'default', glass: true, cta: 'gradient',
+}
+const light = resolveTheme(config, 'light')   // roles, ramps, shadows, radii, contrast report
+const css = generateThemeCss(config)           // [data-ty-theme="lab"] … blocks, all preference media
+const dtcg = themeToDtcg(light)                // DTCG tree
+```
+
+Inputs: seed hue and chroma for six seeds, chart hues, radius base, contrast
+(`default` | `high`), glass on/off, CTA style, optional pinned colours, and
+optionally font families per role (`fonts`, `fontsUrl`) and `elevation`. It is
+pure and deterministic (same input, same output).
+
+**Contrast is enforced, then tested.** Each theme declares 70+ pairs
+(`contrastPairs()`): text roles at 4.5:1 and UI roles (field border, focus ring
+on every surface, brand on sunken tracks, chart colours) at 3:1, with
+translucent layers composited over what sits beneath. The generator nudges any
+non-pinned foreground along its OKLCH lightness axis until the pair passes;
+pinned colours are never changed, and a failing pin fails the build. The tests
+check every pair in every preset × mode × contrast level and a hue sweep of
+custom themes (what the customizer can produce). APCA Lc is computed for every
+pair and reported, not enforced.
+
+## Pipeline choice: Style Dictionary v5
+
+Checked on 2026-09-26: `style-dictionary@5.5.5` and `@terrazzo/cli@2.7.1`.
+Style Dictionary was chosen because:
+
+- its programmatic API (`formatPlatform`) returns output in memory, which lets
+  the build compare its result with the generator's own serialisation (the
+  one the live customizer uses) and fail on any difference;
+- it reads DTCG natively (`usesDtcg`), including 2025.10 colour and dimension
+  objects, and hooks make every value transform ours (colour, shadow,
+  gradient, dimension, duration), so the CSS text is identical from both paths;
+- it is widely used and stable across majors; Terrazzo's native modes are
+  attractive, but the selector strategy here (theme × mode × density ×
+  preference media) is assembled by `src/stylesheet.ts` anyway, which removes
+  that advantage.
+
+## Sources
+
+The concepts taken from public documentation, with the URLs consulted, are
+recorded in `PROVENANCE.md`.
+
+Other references: W3C Design Tokens Community Group format (2025.10); WCAG 2.2
+(1.4.3, 1.4.11, 2.4.7, 2.4.13); Björn Ottosson, "A perceptual color space for
+image processing" (OKLab definition and matrices); the public description of
+the APCA-W3 0.0.98G constants (informational only).