poetry-core 0.0.2

data/lib/poetry/core/stimulus_contract.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module Poetry
+  module Core
+    # The DOM verifier for use_stimulus declarations - PartContract's
+    # stimulus twin: reconciles a component's declared wiring against its
+    # rendered previews, in both directions, so the declarations (and the
+    # registry surface they feed) can never state wiring the component
+    # doesn't render, nor omit wiring it does. Components without
+    # declarations are skipped by callers - the mixed-world rule while the
+    # migration sweeps run.
+    #
+    # Like PartContract.verify, verification is a pure function: the
+    # caller renders the previews and supplies the HTML; nothing here
+    # boots or renders.
+    #
+    # Scoping is by IDENTIFIER, not DOM ownership: wiring a component
+    # forwards into an embedded Button (toast's action slot) speaks the
+    # component's controller and is credited to it wherever it lands;
+    # embedded components' own wiring speaks other identifiers and is
+    # their own previews' business. The one ownership-scoped rule is
+    # foreign-wiring: an OWNED node (nearest data-component is this
+    # component) speaking a manifest-known identifier the declarations
+    # omit - the hand-written-bypass shape.
+    #
+    # Rules (all errors):
+    # - undeclared-controller: a rendered data-controller token of a
+    #   declared identifier that no register entry produces
+    # - undeclared-action:    a rendered action descriptor no declaration
+    #   produces (suggestion carries a paste-ready `action` line)
+    # - undeclared-target:    a rendered target no declaration produces
+    # - undeclared-value:     a rendered value KEY no declaration produces
+    #   (value content is render-time state - keys only)
+    # - phantom-controller / phantom-action / phantom-target /
+    #   phantom-value: declared wiring no preview renders - dead wiring or
+    #   missing preview coverage (the declared-axis coverage rule)
+    # - foreign-wiring:       hand-written wiring for an undeclared,
+    #   manifest-known controller on an owned node
+    #
+    # @api private
+    module StimulusContract
+      module_function
+
+      # @param component [Class] a component class with use_stimulus
+      #   declarations (callers skip undeclared components)
+      # @param docs [Array<String, #css>] every preview render
+      # @return [Array<Check::Finding>]
+      def verify(component:, docs:)
+        elements = component.stimulus_elements.values
+        return [] if elements.empty?
+
+        declared = declared_tokens(elements)
+        rendered = rendered_tokens(component.component_title, docs, declared)
+        findings = []
+        dom_to_declarations(findings, component, declared, rendered)
+        declarations_to_dom(findings, component, declared, rendered)
+        foreign_findings(findings, component, rendered)
+        findings
+      end
+
+      # The declaration side, condition-blind: every entry drives a real
+      # Builder into one Attributes per element, and the emitted hash is
+      # parsed by the SAME parser as the rendered DOM - the two sides'
+      # token formats cannot drift.
+      def declared_tokens(elements)
+        identifiers = elements.flat_map { |element| element.wirings.map(&:identifier) }.uniq
+        tokens = empty_tokens(identifiers)
+        elements.each do |element|
+          attrs = HTML::Attributes.new
+          element.wirings.each do |wiring|
+            builder = Stimulus::Builder.new(wiring.identifier, attrs)
+            wiring.entries.each { |entry| apply_entry(builder, entry) }
+          end
+          collect_attributes(tokens, attrs.to_attributes)
+        end
+        tokens
+      end
+
+      def apply_entry(builder, entry)
+        case entry.kind
+        when :register then builder.register_controller
+        when :value then builder.with_value(entry.name, "declared")
+        when :action then builder.with_action(entry.name, on: entry.on, at: entry.at)
+        when :target then builder.with_target(entry.name)
+        end
+      end
+
+      def rendered_tokens(title, docs, declared)
+        tokens = empty_tokens(declared[:identifiers])
+        docs.each do |doc|
+          doc = Nokogiri::HTML5.fragment(doc.to_s) unless doc.respond_to?(:css)
+          doc.css("*").each do |node|
+            attributes = node.attribute_nodes.to_h { |attribute| [attribute.name, attribute.value.to_s] }
+            collect_attributes(tokens, attributes)
+            collect_foreign(tokens, attributes) if owned?(node, title)
+          end
+        end
+        tokens
+      end
+
+      def empty_tokens(identifiers)
+        { identifiers: identifiers, controllers: Set.new, actions: Set.new,
+          targets: Set.new, values: Set.new, foreign: Set.new }
+      end
+
+      # One parser for both sides. Only tokens speaking a declared
+      # identifier count; scoped keys resolve against the LONGEST known
+      # identifier (manifest + declared), so poetry--core--toaster keys
+      # never misparse as poetry--core--toast values.
+      def collect_attributes(tokens, attributes)
+        attributes.each do |name, value|
+          case name
+          when "data-controller"
+            value.split.each { |token| tokens[:controllers] << token if tokens[:identifiers].include?(token) }
+          when "data-action"
+            value.split.each do |token|
+              tokens[:actions] << token if tokens[:identifiers].include?(action_identifier(token))
+            end
+          else
+            identifier, kind, rest = parse_scoped_key(name, tokens[:identifiers])
+            next unless identifier && tokens[:identifiers].include?(identifier)
+
+            case kind
+            when :target then value.split.each { |target| tokens[:targets] << [identifier, target] }
+            when :value then tokens[:values] << [identifier, rest]
+            end
+          end
+        end
+      end
+
+      # Hand-written wiring for a manifest-known identifier the
+      # declarations omit, on an owned node.
+      def collect_foreign(tokens, attributes)
+        attributes.each do |name, value|
+          case name
+          when "data-controller"
+            value.split.each do |token|
+              tokens[:foreign] << "data-controller=#{token}" if foreign?(token, tokens[:identifiers])
+            end
+          when "data-action"
+            value.split.each do |token|
+              tokens[:foreign] << "data-action=#{token}" if foreign?(action_identifier(token), tokens[:identifiers])
+            end
+          else
+            identifier, = parse_scoped_key(name, tokens[:identifiers])
+            tokens[:foreign] << name if identifier && foreign?(identifier, tokens[:identifiers])
+          end
+        end
+      end
+
+      def foreign?(identifier, declared)
+        !declared.include?(identifier) && Stimulus::Manifest.catalog.key?(identifier)
+      end
+
+      # data-<identifier>-target / data-<identifier>-<name>-value, longest
+      # known identifier first.
+      def parse_scoped_key(name, declared_identifiers)
+        return nil unless name.start_with?("data-") && name.length > 5
+
+        body = name.delete_prefix("data-")
+        known = (Stimulus::Manifest.catalog.keys + declared_identifiers).uniq.sort_by(&:length).reverse
+        known.each do |identifier|
+          next unless body.start_with?(identifier)
+
+          rest = body.delete_prefix(identifier)
+          return [identifier, :target, nil] if rest == "-target"
+          return [identifier, :value, rest.delete_prefix("-").delete_suffix("-value")] if
+            rest.start_with?("-") && rest.end_with?("-value")
+        end
+        nil
+      end
+
+      def action_identifier(token)
+        token.split("->").last.to_s.split("#").first
+      end
+
+      # PartContract's ownership walk: the nearest ancestor-or-self
+      # carrying data-component decides.
+      def owned?(node, title)
+        current = node
+        while current.respond_to?(:key?)
+          return current["data-component"] == title if current.key?("data-component")
+
+          current = current.parent
+        end
+        false
+      end
+
+      def dom_to_declarations(findings, component, declared, rendered)
+        title = component.component_title
+        (rendered[:controllers] - declared[:controllers]).sort.each do |token|
+          findings << finding("undeclared-controller",
+                              "#{title} renders data-controller token #{token.inspect} that no " \
+                              "register declaration produces")
+        end
+        (rendered[:actions] - declared[:actions]).sort.each do |token|
+          findings << finding("undeclared-action",
+                              "#{title} renders action #{token.inspect} that no declaration produces",
+                              suggestion: action_scaffold(token))
+        end
+        (rendered[:targets] - declared[:targets]).sort.each do |(identifier, target)|
+          findings << finding("undeclared-target",
+                              "#{title} renders #{identifier} target #{target.inspect} that no " \
+                              "declaration produces",
+                              suggestion: "target :#{target.underscore}")
+        end
+        (rendered[:values] - declared[:values]).sort.each do |(identifier, key)|
+          findings << finding("undeclared-value",
+                              "#{title} renders #{identifier} value key #{key.inspect} that no " \
+                              "declaration produces",
+                              suggestion: "value :#{key.underscore}")
+        end
+      end
+
+      def declarations_to_dom(findings, component, declared, rendered)
+        title = component.component_title
+        phantom(findings, title, "controller", declared[:controllers] - rendered[:controllers],
+                &:inspect)
+        phantom(findings, title, "action", declared[:actions] - rendered[:actions], &:inspect)
+        phantom(findings, title, "target", declared[:targets] - rendered[:targets]) do |(id, target)|
+          "#{target.inspect} (#{id})"
+        end
+        phantom(findings, title, "value", declared[:values] - rendered[:values]) do |(id, key)|
+          "#{key.inspect} (#{id})"
+        end
+      end
+
+      def phantom(findings, title, kind, missing, &)
+        missing.sort.each do |token|
+          findings << finding("phantom-#{kind}",
+                              "#{title} declares #{kind} #{yield(token)} but no preview " \
+                              "renders it - dead wiring or missing preview coverage")
+        end
+      end
+
+      def foreign_findings(findings, component, rendered)
+        rendered[:foreign].sort.each do |token|
+          findings << finding("foreign-wiring",
+                              "#{component.component_title} hand-writes #{token} for a controller " \
+                              "its declarations omit - declare the wiring (or route it through " \
+                              "stimulus_attributes) so it is validated and published")
+        end
+      end
+
+      def action_scaffold(token)
+        event, descriptor = token.include?("->") ? token.split("->", 2) : [nil, token]
+        method = descriptor.split("#").last.to_s.underscore
+        return "action :#{method}, on: :EVENT" if event.nil?
+
+        event, at = event.split("@", 2)
+        line = "action :#{method}, on: #{event.include?(":") ? event.inspect : ":#{event}"}"
+        line << ", at: :#{at}" if at
+        line
+      end
+
+      def finding(rule, message, suggestion: nil)
+        Check::Finding.new(rule: rule, severity: :error, message: message, suggestion: suggestion)
+      end
+    end
+  end
+end

data/lib/poetry/core/tag_helper.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Core
+    # The view-helper seam: included into ActionView by the engine
+    # (initializer "poetry_core.tag_helper"). Carries no helpers in core.
+    module TagHelper
+    end
+  end
+end

data/lib/poetry/core/template_compile.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Core
+    # The Herb COMPILE gate: every ERB template is fed through
+    # `Herb::Engine` - the same compiler Rails routes templates through when
+    # a host opts into the Herb ERB implementation - so a template that
+    # parses but refuses to compile (ERB output in an attribute name, bare
+    # output in attribute position, an element nested where the validators
+    # forbid it) fails poetry's CI instead of the host's first request.
+    #
+    # Parsing clean (see CSS::TemplateClasses, the parse gate) and
+    # compiling clean are different contracts: the engine runs validators
+    # the parser does not.
+    #
+    # Herb is loaded lazily: it is a build/CI-time tool, not a runtime
+    # dependency of the gem.
+    #
+    # @example
+    #   result = Poetry::Core::TemplateCompile.check(root: Poetry::Core.root)
+    #   result.errors # => [] when every template compiles
+    #
+    # @api private
+    class TemplateCompile
+      # The templates a gem ships: its components + the generator templates
+      # copied verbatim into hosts. Rails renders both through the engine.
+      DEFAULT_GLOBS = ["app/**/*.erb", "lib/generators/**/templates/**/*.erb"].freeze
+
+      CompileError = Struct.new(:path, :message) do
+        def to_s
+          "#{path}: #{message}"
+        end
+      end
+
+      Result = Struct.new(:compiled, :errors)
+
+      class << self
+        # Compiles one ERB source string, returning the engine's error
+        # message or nil when it compiles.
+        #
+        # @return [String, nil]
+        def compile(source, filename: "template.html.erb")
+          herb!
+          Herb::Engine.new(source, filename: filename)
+          nil
+        rescue StandardError => e
+          e.message
+        end
+
+        # Compiles every template under root matching the globs.
+        #
+        # @return [Result] compiled (Integer, templates that compiled) + errors (Array<CompileError>)
+        def check(root:, globs: DEFAULT_GLOBS)
+          errors = []
+          paths = globs.flat_map { |glob| Dir.glob(glob, base: root.to_s) }.uniq.sort
+          paths.each do |relative|
+            message = compile(File.read(File.join(root, relative)), filename: relative)
+            errors << CompileError.new(relative, message) if message
+          end
+          Result.new(paths.size - errors.size, errors)
+        end
+
+        private
+
+        def herb!
+          require "herb"
+        rescue LoadError
+          raise Poetry::Core::Error,
+                "the herb gem is required for the template compile gate - add `gem \"herb\"` to your Gemfile"
+        end
+      end
+    end
+  end
+end

data/lib/poetry/core/token_import.rb

@@ -0,0 +1,317 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Poetry
+  module Core
+    # Design-tool token ingestion (Figma variables, Paper "Copy theme", or any
+    # DTCG / CSS-custom-property source) into the SAME token-override plan the
+    # DESIGN.md importer already runs.
+    #
+    # TokenImport does exactly one job: turn a foreign token export into the
+    # `doc` hash `DesignMd::Import#plan` consumes. Everything downstream is
+    # unchanged, so every imported swatch inherits poetry's contrast law for
+    # free -- the WCAG 2.2 AA gate, the DROP-not-fabricate rule, the
+    # deterministic nearest-AA suggestion, the dark-mode pins. There is no new
+    # verification code here by design: a Figma palette that fails AA is
+    # dropped at the door exactly like a hand-authored DESIGN.md's would be.
+    #
+    # Three input formats, one pipeline (dispatched by extension; the host
+    # tasks poetry:design:import / poetry:figma:import / poetry:paper:import all
+    # funnel through `load`):
+    #
+    #   .json -> figma    : a DTCG / Figma-variables export (plugin shapes vary)
+    #   .css  -> css_vars : a Paper "Copy theme" or drop-in CSS custom-property theme block
+    #   .md   -> DesignMd.parse : the existing DESIGN.md path
+    #
+    # Tolerant like DesignMd.parse: whatever cannot be resolved to a poetry role
+    # or parsed as a color lands in doc["unknown"]["colors"], and the planner
+    # REPORTS it rather than guessing.
+    #
+    # @example
+    #   doc = Poetry::Core::TokenImport.load("figma-variables.json")
+    #   Poetry::Core::DesignMd::Import.new.plan(doc) # the same gated pipeline
+    #
+    # @api private
+    module TokenImport
+      # Path segments (from Figma collections/modes or CSS selectors) that name
+      # a color mode. Anything else defaults to light; poetry then PINS dark
+      # from its shipped defaults for light-only imports (DesignMd::Import).
+      # ("default" is deliberately NOT here -- it collides with the
+      # `primary/DEFAULT` group-leaf convention common in token exports, far
+      # likelier than a Figma mode literally named "Default"; light is the
+      # fallback anyway.)
+      MODES = { "light" => "light", "day" => "light",
+                "dark" => "dark", "night" => "dark" }.freeze
+
+      # Leaf segments that are a wrapper, not the role itself: `primary/DEFAULT`
+      # is the `primary` role, `primary/foreground` is `primary-foreground`.
+      BASE_LEAVES = %w[default base value main].freeze
+      FOREGROUND_LEAVES = %w[foreground fg on text contrast].freeze
+
+      # Grouping segments that carry no semantic role (the DTCG top group, a
+      # collection named "Tokens", etc.). Dropped before role resolution so a
+      # standalone `color/foreground` token is the `foreground` role, not
+      # `color-foreground`, while `primary/foreground` still joins.
+      WRAPPERS = %w[color colors colour colours tokens token theme palette semantic].freeze
+
+      class << self
+        # Dispatch by file extension. Returns a DesignMd `doc` for any source;
+        # markdown falls through to DesignMd.parse so the three host tasks share
+        # one code path.
+        def load(path)
+          content = File.read(path)
+          name = File.basename(path)
+          case File.extname(path).downcase
+          when ".json" then figma(JSON.parse(content), name: name)
+          when ".css"  then css_vars(content, name: name)
+          else DesignMd.parse(content)
+          end
+        end
+
+        # A DTCG / Figma-variables export -> doc. The export
+        # shape varies by plugin (nested groups, collection/mode dimensions,
+        # `{alias}` references, hex strings vs DTCG color objects), so the
+        # walker is deliberately tolerant: it finds every color-ish leaf, keys
+        # it by dotted path AND last segment for alias resolution, then maps
+        # each to a poetry role and mode.
+        def figma(data, name: "figma")
+          leaves = []
+          collect_leaves(data, [], leaves)
+          by_path = leaves.to_h { |leaf| [leaf[:path].join(".").downcase, leaf[:value]] }
+          by_leaf = leaves.to_h { |leaf| [leaf[:path].last.to_s.downcase, leaf[:value]] }
+
+          light = {}
+          dark = {}
+          unknown = {}
+          radius = nil
+
+          leaves.each do |leaf|
+            role = role_name(leaf[:path])
+            if role == "radius"
+              radius ||= dimension_css(leaf[:value])
+              next
+            end
+            next unless color_leaf?(leaf)
+
+            color = resolve_color(leaf[:value], by_path, by_leaf, 0)
+            bucket = detect_mode(leaf[:path]) == "dark" ? dark : light
+            color ? bucket[role] = color : unknown[role] ||= raw_value(leaf[:value])
+          end
+
+          build_doc(name: name, light: light, dark: dark, unknown: unknown, radius: radius)
+        end
+
+        # A CSS custom-property theme (Paper "Copy theme", a drop-in theme block, or a
+        # Tailwind v4 `@theme` block) -> doc. `:root`/`@theme`/`html`/`:host`
+        # blocks are light; a `.dark` (or dark data-attr) block is dark. `var()`
+        # references are resolved within their own mode; concrete hex/oklch/rgb
+        # values parse directly.
+        def css_vars(css, name: "theme")
+          modes = { "light" => {}, "dark" => {} }
+          each_block(css) do |mode, declarations|
+            declarations.each { |var, value| modes[mode][var] = value }
+          end
+
+          light = {}
+          dark = {}
+          unknown = {}
+          radius = nil
+
+          modes.each do |mode, vars|
+            vars.each do |var, raw|
+              role = css_role(var)
+              if role == "radius"
+                radius ||= raw.strip if mode == "light"
+                next
+              end
+              color = resolve_css_value(raw, vars)
+              bucket = mode == "dark" ? dark : light
+              color ? bucket[role] = color : unknown[role] ||= raw.strip
+            end
+          end
+
+          build_doc(name: name, light: light, dark: dark, unknown: unknown, radius: radius)
+        end
+
+        private
+
+        # --- shared -------------------------------------------------------
+
+        def build_doc(name:, light:, dark:, unknown:, radius:)
+          {
+            "name" => name,
+            "theme" => nil,
+            "description" => nil,
+            "colors" => { "light" => light, "dark" => dark },
+            "typography" => { "pairing" => nil, "family" => nil },
+            "radius" => radius,
+            "radius_scale" => nil,
+            "contrast" => nil,
+            "treatment" => nil,
+            "components" => nil,
+            "unknown" => { "colors" => unknown, "sections" => [] }
+          }
+        end
+
+        # Role name from a token path: drop mode segments, treat a DEFAULT/base
+        # leaf as its parent, a foreground/on/text leaf as `<parent>-foreground`,
+        # otherwise the leaf itself. Normalized to poetry's kebab role spelling;
+        # DesignMd::Import's ALIASES + role table decide the final mapping (and
+        # DROP + report anything with no poetry home).
+        def role_name(path)
+          segments = path.map(&:to_s).reject { |s| MODES.key?(s.downcase) || WRAPPERS.include?(s.downcase) }
+          leaf = segments.last.to_s
+          parent = segments[-2]
+          role =
+            if BASE_LEAVES.include?(leaf.downcase) && parent
+              parent
+            elsif FOREGROUND_LEAVES.include?(leaf.downcase) && parent
+              "#{parent}-foreground"
+            else
+              leaf
+            end
+          normalize(role)
+        end
+
+        def detect_mode(path)
+          hit = path.filter_map { |s| MODES[s.to_s.downcase] }.last
+          hit || "light"
+        end
+
+        def normalize(name)
+          name.to_s.strip.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-+|-+\z/, "")
+        end
+
+        # --- DTCG / Figma walking ----------------------------------------
+
+        def collect_leaves(node, path, out)
+          return unless node.is_a?(Hash)
+
+          if token?(node)
+            out << { path: path, value: token_value(node), type: token_type(node) }
+            return
+          end
+
+          node.each do |key, child|
+            next if key.to_s.start_with?("$")
+
+            collect_leaves(child, path + [key.to_s], out)
+          end
+        end
+
+        def token?(node)
+          node.is_a?(Hash) && (node.key?("$value") || (node.key?("value") && node.key?("type")))
+        end
+
+        def token_value(node)
+          node.key?("$value") ? node["$value"] : node["value"]
+        end
+
+        def token_type(node)
+          node["$type"] || node["type"]
+        end
+
+        # A color leaf is one typed "color", or (type-less) one whose value
+        # resolves to a color. Radius is handled separately, before this.
+        def color_leaf?(leaf)
+          type = leaf[:type].to_s.downcase
+          return true if type == "color"
+          return false unless type.empty?
+
+          !color_shape(leaf[:value]).nil?
+        end
+
+        # Resolve a DTCG value (string, alias, or color object) to a Color, or
+        # nil. Aliases (`{group.token}` / `{token}`) chase by dotted path then by
+        # last segment, with a small recursion cap.
+        def resolve_color(value, by_path, by_leaf, depth)
+          return nil if depth > 12
+
+          if value.is_a?(String) && (ref = value[/\A\{(.+)\}\z/, 1])
+            target = by_path[ref.downcase] || by_leaf[ref.split(".").last.to_s.downcase]
+            return target ? resolve_color(target, by_path, by_leaf, depth + 1) : nil
+          end
+
+          color_shape(value)
+        end
+
+        # A concrete DTCG color value -> Color (never an alias here).
+        def color_shape(value)
+          case value
+          when String then Tokens::Color.parse(value)
+          when Hash then color_object(value)
+          end
+        end
+
+        def color_object(obj)
+          space = obj["colorSpace"] || obj["$colorSpace"]
+          if space == "oklch"
+            Tokens::Color.from_dtcg(obj)
+          elsif %w[srgb srgb-linear rgb].include?(space) && obj["components"].is_a?(Array)
+            Tokens::Color.from_srgb(obj["components"].first(3).map(&:to_f), alpha: (obj["alpha"] || 1.0).to_f)
+          elsif (hex = obj["hex"] || obj["value"]).is_a?(String)
+            Tokens::Color.parse(hex)
+          end
+        rescue ArgumentError
+          nil
+        end
+
+        def dimension_css(value)
+          case value
+          when Hash
+            v = value["value"] || value["$value"]
+            v && "#{format("%g", v.to_f)}#{value["unit"] || "px"}"
+          when Numeric then "#{format("%g", value)}px"
+          when String then value.strip
+          end
+        end
+
+        def raw_value(value)
+          value.is_a?(String) ? value.strip : value.inspect
+        end
+
+        # --- CSS custom-property parsing ---------------------------------
+
+        # Yield [mode, {var => value}] for each recognised selector block. Naive
+        # brace matching is fine: token themes are flat declaration blocks.
+        def each_block(css)
+          css.to_s.gsub(%r{/\*.*?\*/}m, "").scan(/([^{}]+)\{([^{}]*)\}/m).each do |selector, body|
+            mode = block_mode(selector.strip)
+            next unless mode
+
+            declarations = body.scan(/--([\w-]+)\s*:\s*([^;]+);/).to_h { |var, value| [var, value.strip] }
+            yield(mode, declarations) unless declarations.empty?
+          end
+        end
+
+        def block_mode(selector)
+          lower = selector.downcase
+          return "dark" if lower.include?(".dark") || lower.include?("data-theme=\"dark\"") ||
+                           lower.include?("data-theme=dark") || lower.include?("[data-mode=dark")
+          return "light" if lower.include?(":root") || lower.start_with?("@theme") ||
+                            lower.include?("html") || lower.include?(":host")
+
+          nil
+        end
+
+        # Drop a leading Tailwind `color-` namespace so `--color-primary` and
+        # `--primary` both land on the `primary` role.
+        def css_role(var)
+          normalize(var.delete_prefix("color-"))
+        end
+
+        def resolve_css_value(raw, vars, depth = 0)
+          return nil if depth > 12
+
+          if (ref = raw.strip[/\Avar\(\s*--([\w-]+)\s*(?:,[^)]*)?\)\z/, 1])
+            target = vars[ref]
+            return target ? resolve_css_value(target, vars, depth + 1) : nil
+          end
+
+          Tokens::Color.parse(raw.strip)
+        end
+      end
+    end
+  end
+end