poetry-core 0.0.2

data/lib/poetry/core/tokens/color.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Core
+    class Tokens
+      # An OKLCH color value (with optional alpha) plus the conversion and
+      # contrast math the AAA-contrast gate is built on:
+      #
+      #   OKLCH -> OKLab -> linear sRGB -> gamma sRGB   (Björn Ottosson's matrices)
+      #   WCAG 2.x relative luminance + contrast ratio
+      #   browser-style alpha compositing (gamma-encoded sRGB blend)
+      #
+      # Pure Ruby, no dependencies - cheap enough to run on every CI build.
+      #
+      # @example
+      #   color = Poetry::Core::Tokens::Color.parse("#1A1C1E")
+      #   color.css # => "oklch(0.225 0.005 248.047)"
+      #   color.contrast_ratio(Poetry::Core::Tokens::Color::WHITE) # => 17.09...
+      class Color
+        # WCAG 2.x contrast shared by Color and Blend: relative luminance is
+        # computed from gamma-encoded sRGB (the value a browser actually paints).
+        module Contrast
+          # WCAG 2.x relative luminance of the painted color.
+          #
+          # @return [Float] 0.0 (black) to 1.0 (white)
+          def luminance
+            r, g, b = srgb.map { |v| v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055)**2.4 }
+            (0.2126 * r) + (0.7152 * g) + (0.0722 * b)
+          end
+
+          # The WCAG contrast ratio against another color, from 1 to 21.
+          #
+          # @param other [#luminance] a Color or Blend
+          # @return [Float]
+          def contrast_ratio(other)
+            pair = [luminance, other.luminance].sort
+            (pair[1] + 0.05) / (pair[0] + 0.05)
+          end
+        end
+
+        # The result of alpha-compositing one color over another: a plain
+        # gamma-encoded sRGB triplet that still knows how to measure contrast.
+        Blend = Struct.new(:srgb) do
+          include Contrast
+        end
+
+        include Contrast
+
+        attr_reader :l, :c, :h, :alpha
+
+        # An OKLCH color; every component is stored as a Float.
+        #
+        # @param l [Numeric] lightness, 0 to 1
+        # @param c [Numeric] chroma
+        # @param h [Numeric] hue, in degrees
+        # @param alpha [Numeric] opacity, 0 to 1
+        def initialize(l:, c: 0.0, h: 0.0, alpha: 1.0)
+          @l = l.to_f
+          @c = c.to_f
+          @h = h.to_f
+          @alpha = alpha.to_f
+        end
+
+        # Build from a DTCG color $value: {"colorSpace" => "oklch",
+        # "components" => [l, c, h], "alpha" => 0.1 (optional)}.
+        #
+        # @param value [Hash] the token's `$value`
+        # @return [Color]
+        # @raise [ArgumentError] for any colorSpace other than oklch
+        def self.from_dtcg(value)
+          color_space = value["colorSpace"]
+          unless color_space == "oklch"
+            raise ArgumentError, "unsupported colorSpace #{color_space.inspect} (only oklch)"
+          end
+
+          l, c, h = value.fetch("components")
+          new(l: l, c: c, h: h, alpha: value.fetch("alpha", 1.0))
+        end
+
+        # Pure white - the literal foreground on destructive surfaces.
+        WHITE = new(l: 1.0)
+        # Pure black - the dark end of the contrast scale, the counterpart
+        # of {WHITE}.
+        BLACK = new(l: 0.0)
+
+        # The CSS color spellings DESIGN.md files carry across the design-skill
+        # ecosystem: poetry emits oklch; foreign-authored files arrive in
+        # hex or rgb().
+        OKLCH_CSS = %r{\Aoklch\(\s*([\d.]+)(%?)\s+([\d.]+)\s+([\d.]+)(?:\s*/\s*([\d.]+)(%?))?\s*\)\z}i
+        # The hex color forms #parse accepts (3/4/6/8 digits).
+        HEX_CSS = /\A#(\h{3}|\h{4}|\h{6}|\h{8})\z/
+        # The rgb()/rgba() color forms #parse accepts.
+        RGB_CSS = %r{\Argba?\(\s*(\d{1,3})\s*[,\s]\s*(\d{1,3})\s*[,\s]\s*(\d{1,3})(?:\s*[,/]\s*([\d.]+)(%?))?\s*\)\z}i
+
+        class << self
+          # Parse a CSS color string into a Color, or nil for anything else
+          # (named colors, var() refs, gradients) - the DESIGN.md importer
+          # DROPS what it cannot parse, never guesses. oklch input keeps its
+          # components verbatim so poetry-authored values round-trip
+          # byte-exact through parse -> css.
+          #
+          # @param css [String, #to_s] a CSS color: oklch(), #hex, rgb()/rgba()
+          # @return [Color, nil]
+          def parse(css)
+            value = css.to_s.strip
+            if (match = value.match(OKLCH_CSS))
+              lightness = match[2] == "%" ? match[1].to_f / 100.0 : match[1].to_f
+              new(l: lightness, c: match[3].to_f, h: match[4].to_f, alpha: parse_alpha(match[5], match[6]))
+            elsif (match = value.match(HEX_CSS))
+              from_hex(match[1])
+            elsif (match = value.match(RGB_CSS))
+              channels = [match[1], match[2], match[3]].map { |channel| channel.to_i / 255.0 }
+              from_srgb(channels, alpha: parse_alpha(match[4], match[5]))
+            end
+          end
+
+          # Gamma-encoded sRGB [0,1] triplet -> Color, via Ottosson's inverse
+          # path (linear sRGB -> LMS -> OKLab -> LCH). Components round to the
+          # 3-decimal precision distributed theme files publish.
+          #
+          # @param srgb [Array<Numeric>] gamma-encoded r, g, b, each in [0, 1]
+          # @param alpha [Numeric] opacity, 0 to 1
+          # @return [Color]
+          def from_srgb(srgb, alpha: 1.0)
+            r, g, b = srgb.map { |v| v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055)**2.4 }
+
+            l_ = Math.cbrt((0.4122214708 * r) + (0.5363325363 * g) + (0.0514459929 * b))
+            m_ = Math.cbrt((0.2119034982 * r) + (0.6806995451 * g) + (0.1073969566 * b))
+            s_ = Math.cbrt((0.0883024619 * r) + (0.2817188376 * g) + (0.6299787005 * b))
+
+            lab_l = (0.2104542553 * l_) + (0.7936177850 * m_) - (0.0040720468 * s_)
+            lab_a = (1.9779984951 * l_) - (2.4285922050 * m_) + (0.4505937099 * s_)
+            lab_b = (0.0259040371 * l_) + (0.7827717662 * m_) - (0.8086757660 * s_)
+
+            chroma = Math.sqrt((lab_a**2) + (lab_b**2))
+            hue = chroma < 1e-4 ? 0.0 : ((Math.atan2(lab_b, lab_a) * 180.0 / Math::PI) % 360.0)
+            new(l: lab_l.clamp(0.0, 1.0).round(3), c: chroma.round(3), h: hue.round(3), alpha: alpha)
+          end
+
+          private
+
+          def from_hex(digits)
+            digits = digits.chars.map { |d| d * 2 }.join if digits.length <= 4
+            channels = digits.scan(/\h{2}/).map { |pair| pair.to_i(16) / 255.0 }
+            from_srgb(channels.first(3), alpha: channels.fetch(3, 1.0))
+          end
+
+          def parse_alpha(raw, percent)
+            return 1.0 if raw.nil?
+
+            percent == "%" ? raw.to_f / 100.0 : raw.to_f
+          end
+        end
+
+        # A copy with any component replaced. The import AA-walk moves L in
+        # fixed steps while chroma holds - deterministic.
+        #
+        # @param l [Numeric] lightness, 0 to 1
+        # @param c [Numeric] chroma
+        # @param h [Numeric] hue, in degrees
+        # @param alpha [Numeric] opacity, 0 to 1
+        # @return [Color]
+        def with(l: self.l, c: self.c, h: self.h, alpha: self.alpha)
+          self.class.new(l: l, c: c, h: h, alpha: alpha)
+        end
+
+        # The CSS serialization, matching the distributed themes' formatting:
+        # "oklch(0.577 0.245 27.325)" / "oklch(1 0 0 / 10%)".
+        #
+        # @return [String]
+        def css
+          base = [l, c, h].map { |v| format("%g", v) }.join(" ")
+          alpha < 1.0 ? "oklch(#{base} / #{format("%g", alpha * 100)}%)" : "oklch(#{base})"
+        end
+
+        # Gamma-encoded sRGB components, each clamped to [0, 1].
+        #
+        # @return [Array<Float>] r, g, b
+        def srgb
+          @srgb ||= linear_srgb.map { |v| v <= 0.0031308 ? 12.92 * v : (1.055 * (v**(1.0 / 2.4))) - 0.055 }
+        end
+
+        # Alpha-composite this color over an opaque background, the way a
+        # browser blends (per-channel, gamma-encoded). Returns a Blend.
+        #
+        # @param background [Color, Blend] the opaque color underneath
+        #   (anything answering #srgb)
+        # @return [Blend]
+        def composite_over(background)
+          blended = srgb.zip(background.srgb).map { |fg, bg| (alpha * fg) + ((1.0 - alpha) * bg) }
+          Blend.new(blended)
+        end
+
+        private
+
+        # OKLCH -> OKLab -> linear sRGB (Ottosson's OKLab matrices), clamped to
+        # gamut. Clamping matches how out-of-gamut CSS colors rasterize.
+        def linear_srgb
+          a = c * Math.cos(h * Math::PI / 180.0)
+          b = c * Math.sin(h * Math::PI / 180.0)
+
+          l_ = (l + (0.3963377774 * a) + (0.2158037573 * b))**3
+          m_ = (l - (0.1055613458 * a) - (0.0638541728 * b))**3
+          s_ = (l - (0.0894841775 * a) - (1.2914855480 * b))**3
+
+          [
+            (+4.0767416621 * l_) - (3.3077115913 * m_) + (0.2309699292 * s_),
+            (-1.2684380046 * l_) + (2.6097574011 * m_) - (0.3413193965 * s_),
+            (-0.0041960863 * l_) - (0.7034186147 * m_) + (1.7076147010 * s_)
+          ].map { |v| v.clamp(0.0, 1.0) }
+        end
+      end
+    end
+  end
+end

data/lib/poetry/core/tokens/contrast_gate.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Core
+    class Tokens
+      # The AAA-contrast CI gate: every semantic
+      # text pair is asserted in BOTH modes against a locked ledger. WCAG 2.2
+      # AA (4.5:1) is the floor; AAA (7:1) is enforced wherever it was
+      # achievable at lock time. A pair may never regress below its locked
+      # class - AAA pairs must stay AAA, AA exceptions must stay >= AA - so
+      # any token change that degrades contrast fails the build.
+      #
+      # The ledger models *rendered* reality: dark destructive is gated as
+      # the theme actually paints it (bg-destructive/60 composited over the page
+      # background - 6.5:1); solid dark destructive under white text is 2.9:1
+      # and therefore a forbidden pattern, documented here.
+      #
+      # @example
+      #   gate = Poetry::Core::Tokens::ContrastGate.new(Poetry::Core::Tokens.load)
+      #   gate.violations # => [] when every locked pair still holds
+      #
+      # @api private
+      class ContrastGate
+        THRESHOLDS = { aaa: 7.0, aa: 4.5 }.freeze
+
+        # Locked against the shipped neutral theme (ratios at lock
+        # in comments). :fg / :bg name color tokens; fg: :white is the literal
+        # (destructive surfaces render text-white; white is not a
+        # token). :bg_alpha + :bg_over composite the bg before measuring.
+        LEDGER = {
+          "light" => [
+            { fg: "foreground",                 bg: "background",      lock: :aaa }, # 19.79
+            { fg: "card-foreground",            bg: "card",            lock: :aaa }, # 19.79
+            { fg: "popover-foreground",         bg: "popover",         lock: :aaa }, # 19.79
+            { fg: "primary-foreground",         bg: "primary",         lock: :aaa }, # 17.16
+            { fg: "secondary-foreground",       bg: "secondary",       lock: :aaa }, # 16.42
+            { fg: "muted-foreground",           bg: "muted",           lock: :aa  }, #  4.54 (parity delta)
+            { fg: "muted-foreground",           bg: "background",      lock: :aa  }, #  4.96
+            { fg: "accent-foreground",          bg: "accent",          lock: :aaa }, # 16.42
+            { fg: :white,                       bg: "destructive",     lock: :aa  }, #  4.76
+            { fg: "sidebar-foreground",         bg: "sidebar",         lock: :aaa }, # 18.96
+            { fg: "sidebar-primary-foreground", bg: "sidebar-primary", lock: :aaa }, # 17.16
+            { fg: "sidebar-accent-foreground",  bg: "sidebar-accent",  lock: :aaa }  # 16.42
+          ].freeze,
+          "dark" => [
+            { fg: "foreground",                 bg: "background",      lock: :aaa }, # 18.96
+            { fg: "card-foreground",            bg: "card",            lock: :aaa }, # 17.16
+            { fg: "popover-foreground",         bg: "popover",         lock: :aaa }, # 17.16
+            { fg: "primary-foreground",         bg: "primary",         lock: :aaa }, # 14.22
+            { fg: "secondary-foreground",       bg: "secondary",       lock: :aaa }, # 14.48
+            { fg: "muted-foreground",           bg: "muted",           lock: :aa  }, #  5.83
+            { fg: "muted-foreground",           bg: "background",      lock: :aaa }, #  7.63
+            { fg: "accent-foreground",          bg: "accent",          lock: :aaa }, # 14.48
+            # Dark mode renders bg-destructive/60 over the page background;
+            # measure the composite (6.48). Solid dark destructive is 2.9:1 -
+            # never paint white text on it undiluted.
+            { fg: :white, bg: "destructive", bg_alpha: 0.6, bg_over: "background", lock: :aa }, # 6.48
+            { fg: "sidebar-foreground",         bg: "sidebar",         lock: :aaa }, # 17.16
+            { fg: "sidebar-primary-foreground", bg: "sidebar-primary", lock: :aa  }, #  6.54 (blue accent)
+            { fg: "sidebar-accent-foreground",  bg: "sidebar-accent",  lock: :aaa }  # 14.48
+          ].freeze
+        }.freeze
+
+        Result = Struct.new(:mode, :label, :ratio, :lock, :pass) do
+          def to_s
+            "[#{mode}] #{label}: #{format("%.2f", ratio)}:1 " \
+              "(locked #{lock.to_s.upcase}, needs >= #{THRESHOLDS.fetch(lock)})"
+          end
+        end
+
+        def initialize(tokens)
+          @tokens = tokens
+        end
+
+        # Every ledger pair measured. The CI test asserts violations.empty?.
+        def results
+          LEDGER.flat_map do |mode, pairs|
+            pairs.map { |spec| measure(mode, spec) }
+          end
+        end
+
+        def violations
+          results.reject(&:pass)
+        end
+
+        # Completeness: every *-foreground token (plus the bare foreground)
+        # must be gated in every mode, so a newly added role can't silently
+        # ship ungated. Returns [mode, name] pairs that are missing.
+        def ungated_foregrounds
+          @tokens.modes.flat_map do |mode|
+            gated = LEDGER.fetch(mode, []).map { |spec| spec[:fg] }
+            @tokens.color_names(mode)
+                   .select { |name| name == "foreground" || name.end_with?("-foreground") }
+                   .reject { |name| gated.include?(name) }
+                   .map { |name| [mode, name] }
+          end
+        end
+
+        private
+
+        def measure(mode, spec)
+          fg = spec[:fg] == :white ? Color::WHITE : @tokens.color(mode, spec[:fg])
+          bg = background_for(mode, spec)
+          ratio = fg.contrast_ratio(bg)
+          label = "#{spec[:fg] == :white ? "white" : spec[:fg]} on #{spec[:bg]}"
+          label += "/#{format("%g", spec[:bg_alpha] * 100)}% over #{spec[:bg_over]}" if spec[:bg_alpha]
+          Result.new(mode, label, ratio, spec[:lock], ratio >= THRESHOLDS.fetch(spec[:lock]))
+        end
+
+        def background_for(mode, spec)
+          base = @tokens.color(mode, spec[:bg])
+          return base unless spec[:bg_alpha]
+
+          translucent = Color.new(l: base.l, c: base.c, h: base.h, alpha: spec[:bg_alpha])
+          translucent.composite_over(@tokens.color(mode, spec[:bg_over]))
+        end
+      end
+    end
+  end
+end

data/lib/poetry/core/tokens/generator.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Poetry
+  module Core
+    class Tokens
+      # Generates every downstream token surface from tokens/tokens.dtcg.json
+      # (the single source of truth):
+      #
+      #   tokens/tokens.css          CSS custom properties (:root + .dark)
+      #   tokens/tailwind-theme.css  Tailwind v4 @theme inline mapping
+      #   DESIGN.md                  front matter regenerated; prose body preserved
+      #
+      # `verify` powers the CI drift gate (rake tokens:verify): committed
+      # artifacts must byte-match a fresh generation, so the canonical JSON
+      # and the shipped CSS/DESIGN.md can never disagree.
+      #
+      # @example
+      #   Poetry::Core::Tokens::Generator.new.verify # => [] when nothing drifted
+      #
+      # @api private
+      class Generator
+        HEADER = "Generated by `bin/rake tokens:generate` from tokens/tokens.dtcg.json - DO NOT EDIT BY HAND."
+
+        # Documented divergences from the reference v4 neutral theme the
+        # compat-var set tracks. Parity
+        # is the default; a delta is only taken when the locked AA floor
+        # demands it, and it must be recorded here.
+        PARITY_DELTAS = [
+          "light muted-foreground: oklch(0.545 0 0) vs the source's 0.556 - darkened to clear the locked WCAG AA " \
+          "floor (4.54:1 on muted, 4.96:1 on background; the source value is 4.34:1 on muted, sub-AA).",
+          "chart-1..5: the source's legacy blue base-color chart ramp (blue-300/500/600/700/800) in both " \
+          "modes - the neutral base ships a gray ramp (0.87 / 0.556 / 0.439 / 0.371 / 0.269) that cannot " \
+          "separate series.",
+          "success, warning, info: poetry additions - the source ships no status roles. success and info " \
+          "reuse source hues (a green base chart hue; the blue ramp's third stop); warning is the orange " \
+          "base's primary. All three are gated like every other role."
+        ].freeze
+
+        # The reference theme's distributed radius scale (@theme inline), in the
+        # MULTIPLICATIVE form of its current distribution rather
+        # than the older additive one: at the default --radius (0.625rem =
+        # 10px) every sm..xl stop computes to the same px (6/8/10/14), so
+        # the form is pixel-neutral, and it brings the 2xl..4xl stops the
+        # style themes use (vega's rounded-2xl toast, rounded-4xl badge).
+        RADIUS_SCALE = {
+          "sm" => "calc(var(--radius) * 0.6)",
+          "md" => "calc(var(--radius) * 0.8)",
+          "lg" => "var(--radius)",
+          "xl" => "calc(var(--radius) * 1.4)",
+          "2xl" => "calc(var(--radius) * 1.8)",
+          "3xl" => "calc(var(--radius) * 2.2)",
+          "4xl" => "calc(var(--radius) * 2.6)"
+        }.freeze
+
+        ARTIFACTS = ["tokens/tokens.css", "tokens/tailwind-theme.css", "DESIGN.md"].freeze
+
+        def initialize(tokens: Tokens.load, root: Poetry::Core.root)
+          @tokens = tokens
+          @root = Pathname.new(root)
+        end
+
+        def tokens_css
+          # color-scheme travels with the mode blocks: UA scrollbars,
+          # form-control chrome, and canvas defaults follow the app's mode
+          # instead of the OS preference - without it, a dark-OS user in a
+          # light app gets dark scrollbars on light surfaces (the same
+          # split-brain the dark: variant remap below closes).
+          lines = ["/* #{HEADER} */", "", ":root {", "  color-scheme: light;",
+                   "  --radius: #{@tokens.radius_css};"]
+          @tokens.color_names("light").each do |name|
+            lines << "  --#{name}: #{@tokens.color("light", name).css};"
+          end
+          lines << "}" << "" << ".dark {" << "  color-scheme: dark;"
+          @tokens.color_names("dark").each do |name|
+            lines << "  --#{name}: #{@tokens.color("dark", name).css};"
+          end
+          lines << "}"
+          "#{lines.join("\n")}\n"
+        end
+
+        def tailwind_theme_css
+          lines = ["/* #{HEADER} */", ""]
+          # poetry dark mode is the .dark CLASS convention. Without
+          # re-mapping Tailwind's dark: variant (whose default is the
+          # prefers-color-scheme media query), a dark-OS user in a light
+          # app gets dark: utilities firing while the .dark tokens do not.
+          # Travels with the theme mapping.
+          lines << "@custom-variant dark (&:where(.dark, .dark *));"
+          lines << ""
+          lines << "@theme inline {"
+          RADIUS_SCALE.each { |step, value| lines << "  --radius-#{step}: #{value};" }
+          @tokens.color_names("light").each do |name|
+            lines << "  --color-#{name}: var(--#{name});"
+          end
+          lines << "}"
+          "#{lines.join("\n")}\n"
+        end
+
+        def design_md
+          "#{front_matter}#{design_md_body}"
+        end
+
+        # Regenerates all artifacts on disk. Returns the written paths.
+        def generate!
+          artifact_contents.map do |relative, content|
+            path = @root.join(relative)
+            path.dirname.mkpath
+            path.write(content)
+            relative
+          end
+        end
+
+        # Relative paths whose on-disk content does not match a fresh
+        # generation (missing or stale). Empty means no drift.
+        def verify
+          artifact_contents.filter_map do |relative, content|
+            path = @root.join(relative)
+            relative unless path.exist? && path.read == content
+          end
+        end
+
+        private
+
+        def artifact_contents
+          {
+            "tokens/tokens.css" => tokens_css,
+            "tokens/tailwind-theme.css" => tailwind_theme_css,
+            "DESIGN.md" => design_md
+          }
+        end
+
+        # The machine-readable half of DESIGN.md: exact tokens + the contrast
+        # policy, regenerated on every pass. The prose constitution below the
+        # front matter is human/agent-authored and preserved verbatim.
+        def front_matter
+          gate = ContrastGate.new(@tokens)
+          data = {
+            "design_system" => "poetry",
+            "source" => Tokens::DEFAULT_RELATIVE_PATH,
+            "generator" => "bin/rake tokens:generate",
+            "dark_mode" => "class .dark",
+            "radius" => @tokens.radius_css,
+            "radius_scale" => RADIUS_SCALE.transform_keys { |k| "radius-#{k}" },
+            "colors" => @tokens.modes.to_h do |mode|
+              [mode, @tokens.color_names(mode).to_h { |n| [n, @tokens.color(mode, n).css] }]
+            end,
+            "contrast_policy" => {
+              "floor" => "WCAG 2.2 AA (4.5:1) - locked, every gated pair",
+              "target" => "AAA (7:1) wherever achievable at lock time",
+              "gate" => "Poetry::Core::Tokens::ContrastGate (CI: rake test)",
+              "aa_exceptions" => gate.results.select { |r| r.lock == :aa }.map(&:to_s)
+            },
+            "parity" => {
+              "base" => "shadcn/ui v4 neutral (cssVarsV4 drop-in var set)",
+              "deltas" => PARITY_DELTAS
+            }
+          }
+          "#{YAML.dump(data)}---\n"
+        end
+
+        def design_md_body
+          existing = @root.join("DESIGN.md")
+          if existing.exist? && (body = existing.read[/\A---\n.*?\n---\n(.*)\z/m, 1])
+            body
+          else
+            STARTER_BODY
+          end
+        end
+
+        STARTER_BODY = <<~BODY
+
+          # DESIGN.md - the poetry design constitution
+
+          The front matter above is **generated** from `tokens/tokens.dtcg.json`
+          (`bin/rake tokens:generate`) and lists the exact tokens; this body is the
+          judgment layer - edit it freely, it is preserved across regenerations.
+
+          ## Principles
+
+          - **Semantic roles only.** Components consume role tokens (`primary`,
+            `destructive`, `muted`, `accent`, ...) - never raw palette values, never
+            hex/oklch literals in markup (enforced by the class Verifier).
+          - **Both modes always.** Every surface must hold in light and dark; dark
+            mode is the `.dark` class convention, and the contrast gate
+            asserts every pair in both modes.
+          - **Contrast is law, not taste.** WCAG 2.2 AA is a locked floor; AAA is
+            enforced where achievable. Exceptions are explicit (front matter) and
+            reviewed - never silent.
+          - **Re-skin at the source.** Restyling the system means editing the DTCG
+            tokens (or dropping in a shadcn v4 theme over `tokens/tokens.css`) and
+            regenerating - one source, every surface.
+
+          ## Do / Don't
+
+          - Do pick variants by intent (one `primary` action per view; `destructive`
+            only for irreversible actions).
+          - Do keep borders subtle (`border`/`input` are deliberately low-contrast;
+            they are not text and are not gated as text).
+          - Don't paint white text on solid `destructive` in dark mode - dark
+            destructive surfaces are rendered at 60% over the background (2.9:1
+            solid vs 6.5:1 composited).
+          - Don't introduce new colors, shadows, or radii without adding tokens
+            here first.
+        BODY
+        private_constant :STARTER_BODY
+      end
+    end
+  end
+end

data/lib/poetry/core/tokens.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Poetry
+  module Core
+    # The canonical design-token model. Loads tokens/tokens.dtcg.json -
+    # the single source of truth - and exposes the semantic color roles per
+    # mode plus the radius dimension. Everything else (tokens.css,
+    # tailwind-theme.css, the DESIGN.md front matter) is generated from an
+    # instance of this class; the AAA-contrast gate asserts against it.
+    #
+    # @example
+    #   tokens = Poetry::Core::Tokens.load
+    #   tokens.color("light", "primary").css # => "oklch(0.205 0 0)"
+    #   tokens.radius_css                    # => "0.625rem"
+    class Tokens
+      # Where the canonical DTCG token file lives, relative to the gem root.
+      DEFAULT_RELATIVE_PATH = "tokens/tokens.dtcg.json"
+
+      # The exact CSS custom-property set of the widely-distributed v4
+      # theme convention (cssVarsV4, plus --radius). This is the drop-in
+      # contract: any theme block written to that convention defines exactly
+      # these names, so it can replace poetry's tokens.css wholesale.
+      SHADCN_V4_COMPAT_VARS = %w[
+        background foreground
+        card card-foreground
+        popover popover-foreground
+        primary primary-foreground
+        secondary secondary-foreground
+        muted muted-foreground
+        accent accent-foreground
+        destructive
+        border input ring
+        chart-1 chart-2 chart-3 chart-4 chart-5
+        sidebar sidebar-foreground
+        sidebar-primary sidebar-primary-foreground
+        sidebar-accent sidebar-accent-foreground
+        sidebar-border sidebar-ring
+      ].freeze
+
+      # Poetry-original extensions BEYOND the compat set: the soft
+      # status vocabulary that set lacks. Kept separate so the
+      # drop-in contract stays sharp: a drop-in theme block replaces the
+      # compat set wholesale, and these keep their poetry defaults unless
+      # the theme chooses to override.
+      POETRY_STATUS_VARS = %w[success warning info].freeze
+
+      class << self
+        # The gem's canonical token file path ({DEFAULT_RELATIVE_PATH}
+        # under the gem root).
+        #
+        # @return [Pathname]
+        def default_path
+          Poetry::Core.root.join(DEFAULT_RELATIVE_PATH)
+        end
+
+        # Loads a DTCG token file into a Tokens instance.
+        #
+        # @param path [String, Pathname] a DTCG JSON file; defaults to the
+        #   gem's canonical tokens
+        # @return [Tokens]
+        def load(path = default_path)
+          new(JSON.parse(File.read(path)))
+        end
+      end
+
+      attr_reader :data
+
+      # Wraps one parsed DTCG document; {.load} is the file-backed form.
+      #
+      # @param data [Hash] the parsed DTCG JSON
+      def initialize(data)
+        @data = data
+        @colors = {}
+      end
+
+      # Mode names ("light", "dark"), skipping DTCG $-metadata keys.
+      #
+      # @return [Array<String>]
+      def modes
+        data.fetch("color").keys.reject { |k| k.start_with?("$") }
+      end
+
+      # The semantic color-role names of one mode, in file order.
+      #
+      # @param mode [String] "light" or "dark"
+      # @return [Array<String>] role names ("primary", "muted-foreground", ...)
+      def color_names(mode)
+        data.fetch("color").fetch(mode).keys.reject { |k| k.start_with?("$") }
+      end
+
+      # The color of one semantic role in one mode.
+      #
+      # @param mode [String] "light" or "dark"
+      # @param name [String] the role name ("primary", "destructive", ...)
+      # @return [Color]
+      # @raise [KeyError] when the mode has no such role
+      def color(mode, name)
+        @colors[[mode, name]] ||= begin
+          token = data.fetch("color").fetch(mode).fetch(name) do
+            raise KeyError, "no #{mode} color token #{name.inspect}"
+          end
+          Color.from_dtcg(token.fetch("$value"))
+        end
+      end
+
+      # The radius dimension as CSS ("0.625rem").
+      #
+      # @return [String]
+      def radius_css
+        value = data.fetch("dimension").fetch("radius").fetch("$value")
+        "#{format("%g", value.fetch("value"))}#{value.fetch("unit")}"
+      end
+    end
+  end
+end

data/lib/poetry/core/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Poetry
+  module Core
+    # The gem version. Every gem in the family carries the same version
+    # and pins poetry-core to it exactly.
+    VERSION = "0.0.2"
+  end
+end