@primitiv-ui/tokens 0.1.28 → 0.1.30

package/README.md

@@ -58,7 +58,7 @@ and `dist/index.html` (UI). Stays running and rebuilds on change.
 ### 4. Load the plugin into Figma desktop (one-time per machine)
 
 In Figma desktop: **Plugins → Development → Import plugin from
-manifest…** and select
+manifest...** and select
 `apps/primitiv-sync-figma-plugin/manifest.json`. After this Figma
 remembers it under **Plugins → Development → Primitiv Sync**.
 
@@ -110,7 +110,7 @@ backup "real".
 ## Conventions
 
 - Slash-separated Figma variable names (`font-family/heading`) become
-  nested DTCG groups (`{ "font-family": { "heading": {…} } }`).
+  nested DTCG groups (`{ "font-family": { "heading": {...} } }`).
 - Each token has `$type` and `$value`. Aliases (next cycle) will use
   DTCG's `{group.sub.name}` reference string.
 - Colours emit as hex: `#rrggbb` opaque, `#rrggbbaa` translucent.
@@ -119,3 +119,31 @@ backup "real".
   key in that file (e.g. `palette.json` has `light` and `dark` keys).
 - Single-mode collections (`Primitives`, `Interaction`) are read from
   `defaultModeId` and emitted flat.
+
+## Dark mode: this repo and Figma encode it *oppositely*
+
+Both are correct. They just put the inversion in different places, and knowing
+which is which is the difference between reading a real bug and inventing one.
+
+| | Where the flip lives | `content/primary` |
+|---|---|---|
+| **This repo** (`intent.json` + `palette.json`) | the **palette** flips per theme (`color.neutral.900` is `#121418` under `light`, `#e5ecf6` under `dark`) | `{color.neutral.900}` in **both** blocks |
+| **Figma** | the **semantic alias** flips; `Primitives / Palette` stays pinned to **Light** on dark frames | `neutral/900` in Light, `neutral/50` in Dark |
+
+So in `intent.json` a semantic token usually names the **same ramp step in both
+blocks** and lets the inverted dark palette do the work; in Figma the palette is
+held still and the alias moves. Emitted CSS follows the repo model — the
+`[data-theme="dark"]` block re-points `--primitiv-color-neutral-*` itself, so
+every semantic token above it can keep one step.
+
+> **Don't diff the two by ramp index.** Doing that reports ~24 bogus mismatches
+> across nearly all of Dark mode (hit 2026-07-28 during the RFC 0022/0023 Figma
+> cross-check). Resolve each side through its own model first: **13 of 23** dark
+> tokens are then byte-identical, and the remaining 10 differ by only 3–9/255
+> because harmoni *generates* the dark ramp instead of literally reversing it, so
+> only the endpoints (`50`↔`900`) mirror exactly. Reviewed and accepted as-is —
+> those interior dark values aren't expressible as a light-palette alias, so
+> there is nothing better for Figma to point at, and retargeting its dark aliases
+> to this repo's steps would resolve them through Palette/Light and turn dark
+> greys pale. The Figma side of this is in the `figma-variable-architecture`
+> skill.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitiv-ui/tokens",
-  "version": "0.1.28",
+  "version": "0.1.30",
   "description": "The DTCG-conformant design-token layer for the Primitiv ecosystem, plus helpers that transform Figma variable exports into DTCG JSON.",
   "type": "module",
   "main": "src/index.ts",

package/src/breakpoint.json

@@ -0,0 +1,10 @@
+{
+  "breakpoint": {
+    "xs": { "$type": "number", "$value": 360 },
+    "sm": { "$type": "number", "$value": 640 },
+    "md": { "$type": "number", "$value": 768 },
+    "lg": { "$type": "number", "$value": 1024 },
+    "xl": { "$type": "number", "$value": 1280 },
+    "2xl": { "$type": "number", "$value": 1536 }
+  }
+}

package/src/code-typography.test.ts

@@ -0,0 +1,64 @@
+import context from './context.json'
+import primitives from './primitives.json'
+
+/*
+ * `code.*` is the mono typographic family — the one every colour value, hex,
+ * ratio and percentage in Harmoni is set in.
+ *
+ * Why this needs a test: the family was authored size-first, so it shipped with
+ * `font-size` and `line-height` and nothing else. That is invisible in the JSON
+ * (a group with two members looks intentional) but it is not a usable family —
+ * a Figma text style binds four members, so `code.*` could not be expressed as
+ * a text style at all, and `font-family.mono` sat in the primitives with
+ * nothing consuming it. This asserts the family is complete *and* that it is
+ * the mono one, which is the whole reason it exists apart from `body`.
+ */
+
+type Mode = 'dense' | 'compact' | 'comfortable' | 'spacious'
+type DtcgNode = { $type?: string; $value?: unknown; [key: string]: unknown }
+
+const MODES: Mode[] = ['dense', 'compact', 'comfortable', 'spacious']
+const SIZES = ['xs', 'sm', 'md', 'lg', 'xl'] as const
+
+/** The members a Figma text style binds, plus the weight the CSS layer needs. */
+const MEMBERS = {
+  'font-family': 'string',
+  'font-weight': 'number',
+  'font-size': 'number',
+  'line-height': 'number',
+  'font-style': 'string',
+} as const
+
+function codeSize(mode: Mode, size: string): DtcgNode {
+  const code = (context as Record<Mode, DtcgNode>)[mode].code as DtcgNode
+  return code[size] as DtcgNode
+}
+
+/** Resolve a DTCG alias (`{font-family.mono}`) against the primitive tree. */
+function resolvePrimitive(ref: string): unknown {
+  const path = ref.slice(1, -1).split('.')
+  let node: DtcgNode = primitives as DtcgNode
+  for (const key of path) node = node[key] as DtcgNode
+  return node.$value
+}
+
+describe('code typography', () => {
+  for (const mode of MODES) {
+    for (const size of SIZES) {
+      it(`${mode} / code / ${size} is a complete typographic family`, () => {
+        const entry = codeSize(mode, size)
+        for (const [member, type] of Object.entries(MEMBERS)) {
+          const node = entry[member] as DtcgNode | undefined
+          expect(node, `${mode}.code.${size}.${member} is missing`).toBeDefined()
+          expect(node?.$type).toBe(type)
+        }
+      })
+
+      it(`${mode} / code / ${size} is set in the mono face`, () => {
+        const family = codeSize(mode, size)['font-family'] as DtcgNode | undefined
+        expect(family?.$value).toBe('{font-family.mono}')
+        expect(resolvePrimitive(family?.$value as string)).toBe('JetBrains Mono')
+      })
+    }
+  }
+})