cleo_design_tokens 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1c372b6959061b875faa56e38b0f8133d1784fb6dfdcde51506703d12502f0f8
+  data.tar.gz: b2ed96b40cbb505dee5238937ad7ae8ea515270ec3538017c0347dda2bfacb45
+SHA512:
+  metadata.gz: 3f2761c8357487e4652bf8e590ea04966692c30cde64113e31fc4c1dabfc5c456666a35e37b454f767eaa8ca4db7f76e34290cb24afcb88eea6f389029fbf7cd
+  data.tar.gz: 0f8939327b3e5c9544f5dab0183fb253b2c66c9b972496d8668e70b2d33f935b324d1a1bdc2e0fd9f270a60d19404c7f24833257017f32216529b1afabb4b0f5

data/lib/cleo_design_tokens/bucket.rb

@@ -0,0 +1,22 @@
+require_relative "errors"
+
+module CleoDesignTokens
+  # Wraps one frozen lookup with a single-argument `fetch`. Exposed so tests
+  # can build one over a fixture lookup, exactly like the module's own
+  # `colors.primitives` below.
+  class Bucket
+    def initialize(lookup)
+      @lookup = lookup
+    end
+
+    def fetch(key)
+      value = @lookup.fetch(key) { raise UnknownTokenError, "unknown design token: #{key.inspect}" }
+      # `Hash#fetch` only guards a missing *key* — a key present with a nil
+      # value (malformed data: a primitive leaf with no `$value`) would
+      # otherwise return nil instead of raising.
+      raise UnknownTokenError, "design token #{key.inspect} has no value" if value.nil?
+
+      value
+    end
+  end
+end

data/lib/cleo_design_tokens/errors.rb

@@ -0,0 +1,5 @@
+module CleoDesignTokens
+  class UnknownTokenError < KeyError; end
+  class UnknownThemeError < ArgumentError; end
+  class DuplicateTokenError < KeyError; end
+end

data/lib/cleo_design_tokens/lookup_builder.rb

@@ -0,0 +1,62 @@
+require_relative "tree_walker"
+require_relative "semantic_entry"
+require_relative "errors"
+
+module CleoDesignTokens
+  # Flattens token trees into frozen key -> value lookups, using TreeWalker.
+  # Exposed as module functions, rather than baked into module load, so the
+  # collision case is testable against fixtures.
+  module LookupBuilder
+    # Flattens one tree of plain (theme-free) leaves — e.g. the parsed
+    # `primitives.json` — into a key -> hex lookup.
+    def self.build_lookup(tree)
+      flatten_tree(tree) { |leaf| leaf["$value"].freeze }
+    end
+
+    # Flattens `semantic.json` into a key -> SemanticEntry lookup, one entry
+    # per role — the theme axis lives inside the entry, not in the key.
+    def self.build_semantic_lookup(tree)
+      flatten_tree(tree) { |leaf| semantic_entry(leaf) }
+    end
+
+    # Walks `tree`, turning each leaf into a lookup entry via the block —
+    # the only thing that differs between the two builders above is how a
+    # leaf becomes a value, so that's the only thing left as a parameter.
+    #
+    # Fails loudly on a collision (two paths normalising to the same key)
+    # rather than letting one silently win, shared here so neither builder
+    # can drift on that guarantee. `origins` maps key -> the *path array*
+    # that produced it, not the key itself — two different paths can
+    # normalise to the same key (e.g. a segment that itself contains a
+    # literal `.`), and storing the path (rather than re-deriving the
+    # identical string) is what lets the error below name both distinctly
+    # instead of printing the same string twice.
+    def self.flatten_tree(tree)
+      lookup = {}
+      origins = {}
+      TreeWalker.walk(tree) do |path, leaf|
+        key = path.join(".")
+        if origins.key?(key)
+          raise DuplicateTokenError,
+                "duplicate design token #{key.inspect}: defined at both " \
+                "#{origins.fetch(key).inspect} and #{path.inspect}"
+        end
+
+        origins[key] = path
+        lookup[key] = yield(leaf)
+      end
+      lookup
+    end
+    private_class_method :flatten_tree
+
+    def self.semantic_entry(leaf)
+      themes = {}
+      (leaf["$themes"] || {}).each { |theme, override| themes[theme] = override["$value"].freeze }
+
+      # `Data#new` freezes the instance itself; the Hash inside it still
+      # needs its own `.freeze` — freezing is shallow.
+      SemanticEntry.new(leaf["$value"]&.freeze, themes.freeze)
+    end
+    private_class_method :semantic_entry
+  end
+end

data/lib/cleo_design_tokens/semantic_bucket.rb

@@ -0,0 +1,39 @@
+require_relative "errors"
+
+module CleoDesignTokens
+  # `theme:` defaults to `"base"` — `$themes` never carries a `"base"` key
+  # (Base isn't an override of itself), so the default and an explicit
+  # `theme: :base` resolve identically with no special-casing.
+  class SemanticBucket
+    THEMES = %w[base chat roast hype].freeze
+    private_constant :THEMES
+
+    def initialize(lookup)
+      @lookup = lookup
+    end
+
+    def fetch(key, theme: "base")
+      theme = theme.to_s
+      raise UnknownThemeError, "unknown theme: #{theme.inspect}" unless THEMES.include?(theme)
+
+      entry = @lookup.fetch(key) { raise UnknownTokenError, "unknown design token: #{key.inspect}" }
+      value = resolve(entry, theme)
+      if value.nil?
+        raise UnknownTokenError,
+              "design token #{key.inspect} has no Base value and no override for theme #{theme.inspect}"
+      end
+
+      value
+    end
+
+    private
+
+    # What a caller gets for (role, theme): the theme's override when it has
+    # one, otherwise the Base value — mirrors transform-core.mjs's
+    # `resolveTheme` exactly. Returns nil when neither exists, which is what
+    # makes `fetch` raise for the Base-less roles.
+    def resolve(entry, theme)
+      entry.themes[theme] || entry.value
+    end
+  end
+end

data/lib/cleo_design_tokens/semantic_entry.rb

@@ -0,0 +1,7 @@
+module CleoDesignTokens
+  # One semantic role: its Base value (nil when the role only exists under a
+  # theme) plus whatever theme overrides genuinely differ from Base. `Data`,
+  # not a `Struct` — this is a fixed value, never mutated after it's built,
+  # and `Data` instances are frozen on construction with no extra `.freeze`.
+  SemanticEntry = Data.define(:value, :themes)
+end

data/lib/cleo_design_tokens/tree_walker.rb

@@ -0,0 +1,28 @@
+module CleoDesignTokens
+  # Walks a token tree, skipping `$`-prefixed keys, yielding each leaf's path
+  # and node to the block. Keys are the JSON path, dot-joined — the files
+  # carry no `color.primitives`/`color.semantic` wrapper to strip, and
+  # segments are already normalised on disk, so there's nothing left for a
+  # caller to do to a path.
+  module TreeWalker
+    # A leaf is `{ "$type" => "color", ... }` — matches transform-core.mjs's
+    # `isLeaf` exactly. A role can carry `$themes` and no `$value` at all
+    # (defined only under a theme, missing from Base in Figma), so `$value`
+    # presence is never part of this check.
+    def self.leaf?(node)
+      node.is_a?(Hash) && node["$type"] == "color"
+    end
+    private_class_method :leaf?
+
+    def self.walk(node, path = [], &on_leaf)
+      return unless node.is_a?(Hash)
+      return on_leaf.call(path, node) if leaf?(node)
+
+      node.each do |child_key, child_value|
+        next if child_key.start_with?("$")
+
+        walk(child_value, path + [child_key], &on_leaf)
+      end
+    end
+  end
+end

data/lib/cleo_design_tokens/version.rb

@@ -0,0 +1,9 @@
+require "json"
+
+module CleoDesignTokens
+  # `package.json`'s `version` is the single source of truth — npm requires
+  # it to be a literal, so it can't defer to us. The gemspec ships
+  # `package.json` alongside `lib/` (see `spec.files`) specifically so this
+  # read works from an installed gem too, not just this source checkout.
+  VERSION = JSON.parse(File.read(File.expand_path("../../package.json", __dir__))).fetch("version")
+end

data/lib/cleo_design_tokens.rb

@@ -0,0 +1,45 @@
+require "json"
+
+# Only what this file references directly. `lookup_builder` pulls in
+# `tree_walker`/`semantic_entry`/`errors` itself, and `bucket`/
+# `semantic_bucket` each pull in `errors` themselves — Ruby's `require` is
+# idempotent, so re-requiring them here would just be noise.
+require_relative "cleo_design_tokens/version"
+require_relative "cleo_design_tokens/lookup_builder"
+require_relative "cleo_design_tokens/bucket"
+require_relative "cleo_design_tokens/semantic_bucket"
+
+# Reads Cleo's canonical colour design tokens (packages/tokens/tokens/color)
+# into two frozen lookups, namespaced by token type then layer, with the
+# theme passed alongside the key rather than baked into it.
+#
+#   CleoDesignTokens.colors.semantic.fetch("core.content.primary")                # => "#47201C"
+#   CleoDesignTokens.colors.semantic.fetch("core.content.primary", theme: :roast) # => "#F8F6F2"
+#   CleoDesignTokens.colors.primitives.fetch("brown.800")                        # => "#47201C"
+module CleoDesignTokens
+  TOKENS_DIR = File.expand_path("../tokens/color", __dir__)
+  PRIMITIVES_PATH = File.join(TOKENS_DIR, "primitives.json")
+  SEMANTIC_PATH = File.join(TOKENS_DIR, "semantic.json")
+
+  # Built at load, into constants — not `@lookup ||=`, which would race under
+  # concurrent access. Frozen from the moment the gem loads, so every reader
+  # in every thread sees the same immutable lookup.
+  PRIMITIVES_LOOKUP = LookupBuilder.build_lookup(JSON.parse(File.read(PRIMITIVES_PATH))).freeze
+  SEMANTIC_LOOKUP = LookupBuilder.build_semantic_lookup(JSON.parse(File.read(SEMANTIC_PATH))).freeze
+
+  # Namespaced by token type (`colors`), then by layer (`primitives`,
+  # `semantic`) — lowercase accessors, not `CleoDesignTokens::Colors::
+  # Semantic.fetch(...)` module nesting, so the call text stays identical to
+  # the TypeScript reader (a colour greps across both repos).
+  #
+  # `Data`, not a plain Hash: `colors.primitives` needs to be an attribute
+  # read (matching the reader's own dot-accessor contract), and a Hash has
+  # no `.primitives` method. Plural `Colors`, not `Color` — an instance
+  # holds both buckets for the `colors` token type, not a single colour.
+  Colors = Data.define(:primitives, :semantic)
+  COLORS = Colors.new(primitives: Bucket.new(PRIMITIVES_LOOKUP), semantic: SemanticBucket.new(SEMANTIC_LOOKUP))
+
+  def self.colors
+    COLORS
+  end
+end

data/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@meetcleo/design-tokens",
+  "version": "0.1.0",
+  "description": "Canonical source of truth for Cleo's design tokens (DTCG JSON), plus a TypeScript reader.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/meetcleo/cleonardo.git",
+    "directory": "packages/tokens"
+  },
+  "homepage": "https://github.com/meetcleo/cleonardo/tree/main/packages/tokens",
+  "bugs": {
+    "url": "https://github.com/meetcleo/cleonardo/issues"
+  },
+  "publishConfig": {
+    "registry": "https://npm.pkg.github.com"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "main": "dist/src/CleoDesignTokens.js",
+  "types": "dist/src/CleoDesignTokens.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/CleoDesignTokens.d.ts",
+      "default": "./dist/src/CleoDesignTokens.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "transform": "node scripts/transform.mjs",
+    "check": "node scripts/transform.mjs --check",
+    "verify": "node scripts/verify-tokens.mjs",
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "yarn build"
+  }
+}