docs-kit 0.1.0

data/app/components/docs_ui/brand_mark.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module DocsUI
+  # Renders a brand/social logo as inline SVG, or falls through to a lucide icon.
+  #
+  #   render DocsUI::BrandMark.new(:github, class: "size-5", label: "GitHub")
+  #
+  # lucide (the kit's synced icon set) ships NO brand logos — it dropped its brand
+  # icons, and rails_icons' brand library (simple_icons) is gone from the current
+  # `icons` gem. So the kit ships its own small, curated set of developer/social
+  # marks (BRANDS below), each an official Simple-Icons 24×24 single-path glyph.
+  #
+  # A token that IS a shipped brand (:github, :discord, …) renders that inline
+  # <svg>. Any other token is treated as a lucide icon name and delegated to
+  # DocsUI::Icon — so `icon: "book-open"` in a topbar link still works, and the
+  # brand set stays additive. The SVG is authored by the kit (a frozen constant),
+  # so `raw(safe(...))` is trusted markup, not config free text.
+  class BrandMark < Phlex::HTML
+    # token => official Simple-Icons path data (viewBox 0 0 24 24, fill rule
+    # nonzero). Sourced verbatim from simpleicons.org; each is a single <path d>.
+    # The path strings are inherently one long line each — never reflow them.
+    # rubocop:disable Layout/LineLength
+    BRANDS = {
+      github: "M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12",
+      gitlab: "m23.6004 9.5927-.0337-.0862L20.3.9814a.851.851 0 0 0-.3362-.405.8748.8748 0 0 0-.9997.0539.8748.8748 0 0 0-.29.4399l-2.2055 6.748H7.5375l-2.2057-6.748a.8573.8573 0 0 0-.29-.4412.8748.8748 0 0 0-.9997-.0537.8585.8585 0 0 0-.3362.4049L.4332 9.5015l-.0325.0862a6.0657 6.0657 0 0 0 2.0119 7.0105l.0113.0087.03.0213 4.976 3.7264 2.462 1.8633 1.4995 1.1321a1.0085 1.0085 0 0 0 1.2197 0l1.4995-1.1321 2.4619-1.8633 5.006-3.7489.0125-.01a6.0682 6.0682 0 0 0 2.0094-7.003z",
+      discord: "M20.317 4.3698a19.7913 19.7913 0 00-4.8851-1.5152.0741.0741 0 00-.0785.0371c-.211.3753-.4447.8648-.6083 1.2495-1.8447-.2762-3.68-.2762-5.4868 0-.1636-.3933-.4058-.8742-.6177-1.2495a.077.077 0 00-.0785-.037 19.7363 19.7363 0 00-4.8852 1.515.0699.0699 0 00-.0321.0277C.5334 9.0458-.319 13.5799.0992 18.0578a.0824.0824 0 00.0312.0561c2.0528 1.5076 4.0413 2.4228 5.9929 3.0294a.0777.0777 0 00.0842-.0276c.4616-.6304.8731-1.2952 1.226-1.9942a.076.076 0 00-.0416-.1057c-.6528-.2476-1.2743-.5495-1.8722-.8923a.077.077 0 01-.0076-.1277c.1258-.0943.2517-.1923.3718-.2914a.0743.0743 0 01.0776-.0105c3.9278 1.7933 8.18 1.7933 12.0614 0a.0739.0739 0 01.0785.0095c.1202.099.246.1981.3728.2924a.077.077 0 01-.0066.1276 12.2986 12.2986 0 01-1.873.8914.0766.0766 0 00-.0407.1067c.3604.698.7719 1.3628 1.225 1.9932a.076.076 0 00.0842.0286c1.961-.6067 3.9495-1.5219 6.0023-3.0294a.077.077 0 00.0313-.0552c.5004-5.177-.8382-9.6739-3.5485-13.6604a.061.061 0 00-.0312-.0286zM8.02 15.3312c-1.1825 0-2.1569-1.0857-2.1569-2.419 0-1.3332.9555-2.4189 2.157-2.4189 1.2108 0 2.1757 1.0952 2.1568 2.419 0 1.3332-.9555 2.4189-2.1569 2.4189zm7.9748 0c-1.1825 0-2.1569-1.0857-2.1569-2.419 0-1.3332.9554-2.4189 2.1569-2.4189 1.2108 0 2.1757 1.0952 2.1568 2.419 0 1.3332-.946 2.4189-2.1568 2.4189Z",
+      x: "M14.234 10.162 22.977 0h-2.072l-7.591 8.824L7.251 0H.258l9.168 13.343L.258 24H2.33l8.016-9.318L16.749 24h6.993zm-2.837 3.299-.929-1.329L3.076 1.56h3.182l5.965 8.532.929 1.329 7.754 11.09h-3.182z",
+      rubygems: "M7.81 7.9l-2.97 2.95 7.19 7.18 2.96-2.95 4.22-4.23-2.96-2.96v-.01H7.8zM12 0L1.53 6v12L12 24l10.47-6V6L12 0zm8.47 16.85L12 21.73l-8.47-4.88V7.12L12 2.24l8.47 4.88v9.73z",
+      bluesky: "M5.202 2.857C7.954 4.922 10.913 9.11 12 11.358c1.087-2.247 4.046-6.436 6.798-8.501C20.783 1.366 24 .213 24 3.883c0 .732-.42 6.156-.667 7.037-.856 3.061-3.978 3.842-6.755 3.37 4.854.826 6.089 3.562 3.422 6.299-5.065 5.196-7.28-1.304-7.847-2.97-.104-.305-.152-.448-.153-.327 0-.121-.05.022-.153.327-.568 1.666-2.782 8.166-7.847 2.97-2.667-2.737-1.432-5.473 3.422-6.3-2.777.473-5.899-.308-6.755-3.369C.42 10.04 0 4.615 0 3.883c0-3.67 3.217-2.517 5.202-1.026",
+      mastodon: "M23.268 5.313c-.35-2.578-2.617-4.61-5.304-5.004C17.51.242 15.792 0 11.813 0h-.03c-3.98 0-4.835.242-5.288.309C3.882.692 1.496 2.518.917 5.127.64 6.412.61 7.837.661 9.143c.074 1.874.088 3.745.26 5.611.118 1.24.325 2.47.62 3.68.55 2.237 2.777 4.098 4.96 4.857 2.336.792 4.849.923 7.256.38.265-.061.527-.132.786-.213.585-.184 1.27-.39 1.774-.753a.057.057 0 0 0 .023-.043v-1.809a.052.052 0 0 0-.02-.041.053.053 0 0 0-.046-.01 20.282 20.282 0 0 1-4.709.545c-2.73 0-3.463-1.284-3.674-1.818a5.593 5.593 0 0 1-.319-1.433.053.053 0 0 1 .066-.054c1.517.363 3.072.546 4.632.546.376 0 .75 0 1.125-.01 1.57-.044 3.224-.124 4.768-.422.038-.008.077-.015.11-.024 2.435-.464 4.753-1.92 4.989-5.604.008-.145.03-1.52.03-1.67.002-.512.167-3.63-.024-5.545zm-3.748 9.195h-2.561V8.29c0-1.309-.55-1.976-1.67-1.976-1.23 0-1.846.79-1.846 2.35v3.403h-2.546V8.663c0-1.56-.617-2.35-1.848-2.35-1.112 0-1.668.668-1.67 1.977v6.218H4.822V8.102c0-1.31.337-2.35 1.011-3.12.696-.77 1.608-1.164 2.74-1.164 1.311 0 2.302.5 2.962 1.498l.638 1.06.638-1.06c.66-.999 1.65-1.498 2.96-1.498 1.13 0 2.043.395 2.74 1.164.675.77 1.012 1.81 1.012 3.12z",
+      slack: "M5.042 15.165a2.528 2.528 0 0 1-2.52 2.523A2.528 2.528 0 0 1 0 15.165a2.527 2.527 0 0 1 2.522-2.52h2.52v2.52zM6.313 15.165a2.527 2.527 0 0 1 2.521-2.52 2.527 2.527 0 0 1 2.521 2.52v6.313A2.528 2.528 0 0 1 8.834 24a2.528 2.528 0 0 1-2.521-2.522v-6.313zM8.834 5.042a2.528 2.528 0 0 1-2.521-2.52A2.528 2.528 0 0 1 8.834 0a2.528 2.528 0 0 1 2.521 2.522v2.52H8.834zM8.834 6.313a2.528 2.528 0 0 1 2.521 2.521 2.528 2.528 0 0 1-2.521 2.521H2.522A2.528 2.528 0 0 1 0 8.834a2.528 2.528 0 0 1 2.522-2.521h6.312zM18.956 8.834a2.528 2.528 0 0 1 2.522-2.521A2.528 2.528 0 0 1 24 8.834a2.528 2.528 0 0 1-2.522 2.521h-2.522V8.834zM17.688 8.834a2.528 2.528 0 0 1-2.523 2.521 2.527 2.527 0 0 1-2.52-2.521V2.522A2.527 2.527 0 0 1 15.165 0a2.528 2.528 0 0 1 2.523 2.522v6.312zM15.165 18.956a2.528 2.528 0 0 1 2.523 2.522A2.528 2.528 0 0 1 15.165 24a2.527 2.527 0 0 1-2.52-2.522v-2.522h2.52zM15.165 17.688a2.527 2.527 0 0 1-2.52-2.523 2.526 2.526 0 0 1 2.52-2.52h6.313A2.527 2.527 0 0 1 24 15.165a2.528 2.528 0 0 1-2.522 2.523h-6.313z",
+      whatsapp: "M17.472 14.382c-.297-.149-1.758-.867-2.03-.967-.273-.099-.471-.148-.67.15-.197.297-.767.966-.94 1.164-.173.199-.347.223-.644.075-.297-.15-1.255-.463-2.39-1.475-.883-.788-1.48-1.761-1.653-2.059-.173-.297-.018-.458.13-.606.134-.133.298-.347.446-.52.149-.174.198-.298.298-.497.099-.198.05-.371-.025-.52-.075-.149-.669-1.612-.916-2.207-.242-.579-.487-.5-.669-.51-.173-.008-.371-.01-.57-.01-.198 0-.52.074-.792.372-.272.297-1.04 1.016-1.04 2.479 0 1.462 1.065 2.875 1.213 3.074.149.198 2.096 3.2 5.077 4.487.709.306 1.262.489 1.694.625.712.227 1.36.195 1.871.118.571-.085 1.758-.719 2.006-1.413.248-.694.248-1.289.173-1.413-.074-.124-.272-.198-.57-.347m-5.421 7.403h-.004a9.87 9.87 0 01-5.031-1.378l-.361-.214-3.741.982.998-3.648-.235-.374a9.86 9.86 0 01-1.51-5.26c.001-5.45 4.436-9.884 9.888-9.884 2.64 0 5.122 1.03 6.988 2.898a9.825 9.825 0 012.893 6.994c-.003 5.45-4.437 9.884-9.885 9.884m8.413-18.297A11.815 11.815 0 0012.05 0C5.495 0 .16 5.335.157 11.892c0 2.096.547 4.142 1.588 5.945L.057 24l6.305-1.654a11.882 11.882 0 005.683 1.448h.005c6.554 0 11.89-5.335 11.893-11.893a11.821 11.821 0 00-3.48-8.413Z",
+      telegram: "M11.944 0A12 12 0 0 0 0 12a12 12 0 0 0 12 12 12 12 0 0 0 12-12A12 12 0 0 0 12 0a12 12 0 0 0-.056 0zm4.962 7.224c.1-.002.321.023.465.14a.506.506 0 0 1 .171.325c.016.093.036.306.02.472-.18 1.898-.962 6.502-1.36 8.627-.168.9-.499 1.201-.82 1.23-.696.065-1.225-.46-1.9-.902-1.056-.693-1.653-1.124-2.678-1.8-1.185-.78-.417-1.21.258-1.91.177-.184 3.247-2.977 3.307-3.23.007-.032.014-.15-.056-.212s-.174-.041-.249-.024c-.106.024-1.793 1.14-5.061 3.345-.48.33-.913.49-1.302.48-.428-.008-1.252-.241-1.865-.44-.752-.245-1.349-.374-1.297-.789.027-.216.325-.437.893-.663 3.498-1.524 5.83-2.529 6.998-3.014 3.332-1.386 4.025-1.627 4.476-1.635z",
+      linkedin: "M20.447 20.452h-3.554v-5.569c0-1.328-.027-3.037-1.852-3.037-1.853 0-2.136 1.445-2.136 2.939v5.667H9.351V9h3.414v1.561h.046c.477-.9 1.637-1.85 3.37-1.85 3.601 0 4.267 2.37 4.267 5.455v6.286zM5.337 7.433c-1.144 0-2.063-.926-2.063-2.065 0-1.138.92-2.063 2.063-2.063 1.14 0 2.064.925 2.064 2.063 0 1.139-.925 2.065-2.064 2.065zm1.782 13.019H3.555V9h3.564v11.452zM22.225 0H1.771C.792 0 0 .774 0 1.729v20.542C0 23.227.792 24 1.771 24h20.451C23.2 24 24 23.227 24 22.271V1.729C24 .774 23.2 0 22.222 0h.003z",
+      youtube: "M23.498 6.186a3.016 3.016 0 0 0-2.122-2.136C19.505 3.545 12 3.545 12 3.545s-7.505 0-9.377.505A3.017 3.017 0 0 0 .502 6.186C0 8.07 0 12 0 12s0 3.93.502 5.814a3.016 3.016 0 0 0 2.122 2.136c1.871.505 9.376.505 9.376.505s7.505 0 9.377-.505a3.015 3.015 0 0 0 2.122-2.136C24 15.93 24 12 24 12s0-3.93-.502-5.814zM9.545 15.568V8.432L15.818 12l-6.273 3.568z",
+      reddit: "M12 0C5.373 0 0 5.373 0 12c0 3.314 1.343 6.314 3.515 8.485l-2.286 2.286C.775 23.225 1.097 24 1.738 24H12c6.627 0 12-5.373 12-12S18.627 0 12 0Zm4.388 3.199c1.104 0 1.999.895 1.999 1.999 0 1.105-.895 2-1.999 2-.946 0-1.739-.657-1.947-1.539v.002c-1.147.162-2.032 1.15-2.032 2.341v.007c1.776.067 3.4.567 4.686 1.363.473-.363 1.064-.58 1.707-.58 1.547 0 2.802 1.254 2.802 2.802 0 1.117-.655 2.081-1.601 2.531-.088 3.256-3.637 5.876-7.997 5.876-4.361 0-7.905-2.617-7.998-5.87-.954-.447-1.614-1.415-1.614-2.538 0-1.548 1.255-2.802 2.803-2.802.645 0 1.239.218 1.712.585 1.275-.79 2.881-1.291 4.64-1.365v-.01c0-1.663 1.263-3.034 2.88-3.207.188-.911.993-1.595 1.959-1.595Zm-8.085 8.376c-.784 0-1.459.78-1.506 1.797-.047 1.016.64 1.429 1.426 1.429.786 0 1.371-.369 1.418-1.385.047-1.017-.553-1.841-1.338-1.841Zm7.406 0c-.786 0-1.385.824-1.338 1.841.047 1.017.634 1.385 1.418 1.385.785 0 1.473-.413 1.426-1.429-.046-1.017-.721-1.797-1.506-1.797Zm-3.703 4.013c-.974 0-1.907.048-2.77.135-.147.015-.241.168-.183.305.483 1.154 1.622 1.964 2.953 1.964 1.33 0 2.47-.81 2.953-1.964.057-.137-.037-.29-.184-.305-.863-.087-1.795-.135-2.769-.135Z",
+      stackoverflow: "M15.725 0l-1.72 1.277 6.39 8.588 1.716-1.277L15.725 0zm-3.94 3.418l-1.369 1.644 8.225 6.85 1.369-1.644-8.225-6.85zm-3.15 4.465l-.905 1.94 9.702 4.517.904-1.94-9.701-4.517zm-1.85 4.86l-.44 2.093 10.473 2.201.44-2.092-10.473-2.203zM1.89 15.47V24h19.19v-8.53h-2.133v6.397H4.021v-6.396H1.89zm4.265 2.133v2.13h10.66v-2.13H6.154Z"
+    }.freeze
+    # rubocop:enable Layout/LineLength
+
+    # True when `token` names a shipped brand mark (symbol or string), false for a
+    # lucide name, nil, or a blank string. The Shell uses this to decide whether a
+    # topbar link's icon renders as a brand <svg> or a lucide glyph.
+    def self.brand?(token)
+      return false if token.nil? || token.to_s.empty?
+
+      BRANDS.key?(token.to_sym)
+    end
+
+    # icon:  a brand key (:github, …) or a lucide icon name.
+    # label: the accessible name — rendered as the SVG <title> (brand) so a
+    #        screen reader announces "GitHub", never an empty graphic.
+    def initialize(icon, label: nil, **attributes)
+      @icon = icon
+      @label = label
+      @attributes = attributes
+    end
+
+    def view_template
+      if self.class.brand?(@icon)
+        brand_svg
+      else
+        # Not a shipped brand — treat the token as a lucide icon name. Threads the
+        # same attributes (class, etc.); DocsUI::Icon degrades to nothing if the
+        # name isn't synced, exactly as elsewhere in the chrome.
+        render DocsUI::Icon.new(@icon.to_s, **@attributes)
+      end
+    end
+
+    private
+
+    # The inline brand <svg>. The path comes from the frozen BRANDS constant
+    # (kit-authored, never config free text), so raw(safe(...)) is trusted markup.
+    def brand_svg
+      svg(
+        xmlns: "http://www.w3.org/2000/svg",
+        viewBox: "0 0 24 24",
+        fill: "currentColor",
+        role: "img",
+        aria_label: @label,
+        **@attributes
+      ) do
+        title { @label } if @label
+        raw(safe(%(<path d="#{BRANDS[@icon.to_sym]}"/>)))
+      end
+    end
+  end
+end

data/app/components/docs_ui/callout.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module DocsUI
+  # A callout box (note / tip / warning) for the docs. daisyUI alert styling + a
+  # lucide icon per level.
+  #
+  #   render DocsUI::Callout.new(:warning) { "Restart the server after…" }
+  class Callout < Phlex::HTML
+    LEVELS = {
+      note: { klass: "alert-info", icon: "info" },
+      tip: { klass: "alert-success", icon: "lightbulb" },
+      warning: { klass: "alert-warning", icon: "triangle-alert" }
+    }.freeze
+
+    def initialize(level = :note, title: nil)
+      # Normalize an unknown level to :note so both the styling and the
+      # data-md-callout export hint agree (never a bogus level name leaking out).
+      @level = LEVELS.key?(level) ? level : :note
+      @config = LEVELS[@level]
+      @title = title
+    end
+
+    def view_template(&)
+      # data-md-callout carries the level (note/tip/warning) so
+      # DocsKit::MarkdownExport renders `> **Tip:** …` without reverse-engineering
+      # the level from the alert-* class.
+      div(class: "not-prose alert #{@config[:klass]} my-4 items-start", role: "note",
+          data: { md_callout: @level }) do
+        render DocsUI::Icon.new(@config[:icon], class: "size-5 shrink-0")
+        div do
+          div(class: "font-semibold") { @title } if @title
+          div(class: "text-sm", &)
+        end
+      end
+    end
+  end
+end

data/app/components/docs_ui/code.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "rouge"
+
+module DocsUI
+  # A syntax-highlighted code block for docs and demo panels. Rouge does the
+  # highlighting; an optional filename/label sits in a title bar like a real docs
+  # code sample. Self-contained: it injects its own Rouge theme CSS so no separate
+  # stylesheet asset is required.
+  #
+  #   render DocsUI::Code.new(ruby_source)                          # ruby, no title
+  #   render DocsUI::Code.new(py, lexer: :python, filename: "a.py")  # any language
+  #
+  # Any language Rouge knows (~200 lexers) works by its name or alias — python,
+  # go, rust, elixir, kotlin, swift, json, dockerfile, ... — no allowlist. Add
+  # friendly lexer aliases via DocsKit.configure (code_lexer_aliases). An unknown
+  # language falls back to plaintext (never raises). (Tab labels are a
+  # DocsUI::Example concern — set via code_language_labels, not here; Code has no
+  # label, only a filename.)
+  class Code < Phlex::HTML
+    include Phlex::Rails::Helpers::ContentSecurityPolicyNonce
+
+    FORMATTER = Rouge::Formatters::HTML.new
+
+    def initialize(source, lexer: :ruby, filename: nil)
+      @source = source.to_s.strip
+      @lexer = lexer
+      @filename = filename
+    end
+
+    def view_template
+      # Nonce the inline theme CSS so it survives a nonce-based style-src. Off a
+      # request there is no nonce (see #csp_nonce) and Phlex omits a nil-valued
+      # attribute, so the no-nonce markup is unchanged.
+      style(nonce: csp_nonce) { highlight_css }
+      resolved = lexer
+      div(class: "not-prose my-4 overflow-hidden rounded-box border border-base-300 bg-base-300/40") do
+        title_bar if @filename
+        # data-md-lang carries the RESOLVED Rouge tag (ruby/python/plaintext/…) so
+        # DocsKit::MarkdownExport emits a ```lang fence without re-resolving the
+        # language. It's the real lexer tag, not the requested alias.
+        div(class: "code-highlight overflow-x-auto p-4 text-sm leading-relaxed", data: { md_lang: resolved.tag }) do
+          pre { raw(safe(FORMATTER.format(resolved.lex(@source)))) }
+        end
+      end
+    end
+
+    private
+
+    # The request's CSP nonce, or nil when there's no Rails view context (an
+    # isolated Phlex render, or a host that doesn't nonce style-src). The
+    # phlex-rails value helper delegates to view_context, which raises without
+    # one, so guard on its presence — a nil result makes Phlex omit the
+    # attribute, keeping the un-nonced markup unchanged.
+    def csp_nonce = view_context && content_security_policy_nonce
+
+    def title_bar
+      # data-md-skip: the title bar is chrome. MarkdownExport strips it whole
+      # before the visitor runs, so the filename never leaks into the .md twin as
+      # a stray line above the fence. The visible HTML is unaffected (DROP_SELECTOR
+      # is applied only inside #to_md).
+      div(class: "flex items-center gap-2 border-b border-base-300 bg-base-300/60 px-4 py-2",
+          data: { md_skip: true }) do
+        render DocsUI::Icon.new("file-code", class: "size-3.5 opacity-60")
+        span(class: "font-mono text-xs opacity-70") { @filename }
+      end
+    end
+
+    # Resolve @lexer to a Rouge lexer instance. Order: an explicit Rouge::Lexer
+    # class/instance passed through; a configured friendly alias; Rouge's own
+    # registry (name/alias); then the configured fallback (plaintext).
+    def lexer
+      explicit_lexer || (find_lexer(@lexer.to_s) || Rouge::Lexers::PlainText).new
+    end
+
+    # A Rouge::Lexer instance passed directly (class or instance), else nil.
+    def explicit_lexer
+      return @lexer if @lexer.is_a?(Rouge::Lexer)
+      return @lexer.new if @lexer.is_a?(Class) && @lexer < Rouge::Lexer
+
+      nil
+    end
+
+    # Find a lexer CLASS by name: configured alias → Rouge registry → fallback.
+    def find_lexer(name)
+      config = DocsKit.configuration
+      aliased = config.lexer_aliases[name.to_sym]
+      (aliased && Rouge::Lexer.find(aliased.to_s)) ||
+        Rouge::Lexer.find(name) ||
+        Rouge::Lexer.find(config.code_lexer_fallback.to_s)
+    end
+
+    # Static Rouge theme CSS — no user input. Phlex safe(), not html_safe.
+    #
+    # The base (light) theme is emitted un-scoped so it applies to every theme.
+    # When a dark theme is configured (config.code_theme_dark), its CSS is
+    # additionally emitted scoped under [data-theme=X] .code-highlight for each
+    # shipped dark theme, so daisyUI's more-specific [data-theme] selector wins
+    # and code blocks restyle with the switcher — CSS-only, no JS, no flash.
+    # With no dark theme configured this reduces to the original single-theme
+    # output byte-for-byte (backwards compatible).
+    def highlight_css
+      theme = DocsKit.configuration.code_theme_class
+      raw(safe(<<~CSS))
+        #{theme.render(scope: '.code-highlight')}#{dark_highlight_css}
+        .code-highlight pre { margin: 0; white-space: pre-wrap; word-break: break-word; }
+      CSS
+    end
+
+    # The dark theme's CSS, one block per shipped dark theme, each scoped under
+    # [data-theme=X] .code-highlight. Empty string when no dark theme is
+    # configured (or no shipped theme is dark) so #highlight_css is unchanged.
+    def dark_highlight_css
+      config = DocsKit.configuration
+      dark = config.code_theme_dark_class
+      return "" if dark.nil?
+
+      config.dark_themes_shipped.map do |name|
+        "\n#{dark.render(scope: "[data-theme=#{name}] .code-highlight")}"
+      end.join
+    end
+  end
+end

data/app/components/docs_ui/endpoint.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module DocsUI
+  # An HTTP endpoint reference line — a method badge followed by the path — in the
+  # kit's daisyUI look. This is the `code(class: "badge …")` lambda every API page
+  # was hand-rolling; compose it instead.
+  #
+  #   render DocsUI::Endpoint.new(:post, "/v1/messages")
+  #   # => POST /v1/messages   (POST as a primary badge, path monospace)
+  #
+  # It renders INLINE (no block wrapper), so it drops straight into a Section
+  # description or a run of prose:
+  #
+  #   DocsUI::Section("Create a message", description: DocsUI::Endpoint.new(:post, "/v1/messages"))
+  #
+  # The verb → badge-colour map is an explicit frozen Hash of LITERAL class
+  # strings so the Tailwind scan (which reads the gem's Ruby) sees every badge
+  # class and generates it. An unknown verb falls back to a neutral badge and
+  # never raises — a typo degrades gracefully rather than blowing up a render.
+  class Endpoint < Phlex::HTML
+    # Each value is a single literal string (not interpolated) so Tailwind's
+    # source scan generates the colour. Keep these literal — see Critical Rule 6.
+    BADGE_CLASSES = {
+      "GET" => "badge badge-sm badge-success",
+      "POST" => "badge badge-sm badge-primary",
+      "PUT" => "badge badge-sm badge-warning",
+      "PATCH" => "badge badge-sm badge-warning",
+      "DELETE" => "badge badge-sm badge-error"
+    }.freeze
+
+    NEUTRAL_BADGE = "badge badge-sm badge-neutral"
+
+    def initialize(method, path)
+      @method = method.to_s.upcase
+      @path = path
+    end
+
+    def view_template
+      code(class: BADGE_CLASSES.fetch(@method, NEUTRAL_BADGE)) { plain @method }
+      whitespace
+      code { plain @path }
+    end
+  end
+end

data/app/components/docs_ui/error_table.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module DocsUI
+  # An error reference table for an API endpoint — a keyword-schema preset over
+  # DocsUI::Table. Each error is a Hash:
+  #
+  #   render DocsUI::ErrorTable.new(
+  #     [
+  #       { scenario: "Missing or invalid API key", status: "401", type: "authentication_error" },
+  #       { scenario: "Non-HTTPS URL",              status: "422", type: "validation_error", param: "url" },
+  #     ]
+  #   )
+  #
+  # Columns: Scenario / Status / Type (auto code-styled) / Param (auto code-styled).
+  # The Param column is shown only when at least one error names a param — an
+  # endpoint whose errors are all param-free renders a clean three-column table.
+  # When the column IS shown, a param-free row gets the canonical em-dash `—`.
+  #
+  # `type:` is optional — OpenAPI has no canonical error-type field, so an
+  # OpenAPI-derived error may carry none. A row without a (present) type gets the
+  # em-dash `—` in the Type column, not an empty <code>; a row with `type:`
+  # renders it code-styled exactly as before.
+  class ErrorTable < Phlex::HTML
+    BASE_HEADERS = %w[Scenario Status Type].freeze
+    PARAM_HEADER = "Param"
+
+    # Shared with FieldTable's canonical "no value" placeholder.
+    NO_PARAM = "—"
+
+    def initialize(errors)
+      @errors = errors
+      @with_param = errors.any? { |error| present_param?(error[:param]) }
+    end
+
+    def view_template
+      render DocsUI::Table.new(headers, @errors.map { |error| row(error) })
+    end
+
+    private
+
+    def headers
+      @with_param ? [*BASE_HEADERS, PARAM_HEADER] : BASE_HEADERS
+    end
+
+    def row(error)
+      cells = [
+        error.fetch(:scenario),
+        error.fetch(:status),
+        type_cell(error)
+      ]
+      cells << param_cell(error) if @with_param
+      cells
+    end
+
+    # The Type cell: code-styled when present, else the em-dash placeholder. A
+    # blank string counts as absent (same rule as #param_cell / #present_param?).
+    def type_cell(error)
+      type = error[:type]
+      present_param?(type) ? [:code, type] : NO_PARAM
+    end
+
+    def param_cell(error)
+      param = error[:param]
+      present_param?(param) ? [:code, param] : NO_PARAM
+    end
+
+    # A blank string is not a param — it flips no column and gets the em-dash.
+    def present_param?(param)
+      !param.nil? && !param.to_s.strip.empty?
+    end
+  end
+end

data/app/components/docs_ui/example.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module DocsUI
+  # A multi-language code group: the same example shown in several languages, with
+  # tabs to switch. The chosen language is a GLOBAL sticky preference (localStorage
+  # via the docs-nav controller) — pick Ruby once and every code group on this and
+  # future pages shows Ruby, falling back to an available language when a group
+  # doesn't have the chosen one.
+  #
+  #   render DocsUI::Example.new do |ex|
+  #     ex.code(:ruby, filename: "client.rb") do
+  #       <<~RUBY
+  #         Anthropic.messages.create(model: "claude-opus-4-8", ...)
+  #       RUBY
+  #     end
+  #     ex.code(:python, filename: "client.py") do
+  #       <<~PY
+  #         client.messages.create(model="claude-opus-4-8", ...)
+  #       PY
+  #     end
+  #   end
+  #
+  # With one snippet it degrades to a plain DocsUI::Code (no tabs). With JS off the
+  # first language shows and the rest are visible below it (progressive
+  # enhancement — no content is hidden without JS).
+  class Example < Phlex::HTML
+    def initialize
+      @snippets = []
+    end
+
+    # Collect one language's snippet. `lang` is the language token (e.g. :ruby,
+    # :python, :go) — Docs::Code resolves it against Rouge's full registry + the
+    # configured aliases, so any language works. The tab label comes from the
+    # configured language_labels (else the token capitalized), or an explicit
+    # `label:` override (used by RequestExample so a client carries its own tab
+    # name). filename/lexer are optional; lexer defaults to the language token.
+    # The block returns the source.
+    def code(lang, filename: nil, lexer: nil, label: nil)
+      token = lang.to_sym
+      @snippets << {
+        lang: token,
+        label: label || DocsKit.configuration.language_labels.fetch(token, token.to_s.capitalize),
+        filename: filename,
+        lexer: lexer || token,
+        source: yield.to_s
+      }
+      nil
+    end
+
+    def view_template
+      yield self if block_given?
+      return if @snippets.empty?
+      return render_single if @snippets.one?
+
+      div(
+        class: "not-prose my-4",
+        data: { docs_nav_target: "codeGroup" }
+      ) do
+        language_tabs
+        snippet_panels
+      end
+    end
+
+    private
+
+    def render_single
+      snippet = @snippets.first
+      render DocsUI::Code.new(snippet[:source], lexer: snippet[:lexer], filename: snippet[:filename])
+    end
+
+    def language_tabs
+      div(role: "tablist", class: "tabs tabs-box w-fit mb-2") do
+        @snippets.each do |snippet|
+          button(
+            role: "tab",
+            class: "tab",
+            data: {
+              docs_nav_target: "codeTab",
+              docs_nav_lang_param: snippet[:lang],
+              action: "docs-nav#selectLanguage",
+              testid: "code-lang-#{snippet[:lang]}"
+            }
+          ) { snippet[:label] }
+        end
+      end
+    end
+
+    def snippet_panels
+      @snippets.each do |snippet|
+        div(
+          data: {
+            docs_nav_target: "codePanel",
+            docs_nav_lang_param: snippet[:lang],
+            lang: snippet[:lang]
+          }
+        ) do
+          render DocsUI::Code.new(snippet[:source], lexer: snippet[:lexer], filename: snippet[:filename])
+        end
+      end
+    end
+  end
+end

data/app/components/docs_ui/field_table.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module DocsUI
+  # A parameter/field reference table for an API object or request body — a
+  # keyword-schema preset over DocsUI::Table. Each field is a Hash:
+  #
+  #   render DocsUI::FieldTable.new(
+  #     [
+  #       { name: "url",         type: "string", required: true, description: "HTTPS destination URL." },
+  #       { name: "description", type: "string",                 description: "Optional internal label." },
+  #       { name: "events",      type: "array",  required: true, description: [:md, "e.g. `payment_link.paid`"] },
+  #     ]
+  #   )
+  #
+  # Columns: Name (auto code-styled) / Type / Required (✓ or the canonical em-dash
+  # `—`) / Description. `required:` defaults to false. The description cell follows
+  # DocsUI::Table's convention — a plain String is escaped text, `[:code, "x"]` is
+  # inline code, `[:md, "…"]` is inline Markdown.
+  class FieldTable < Phlex::HTML
+    HEADERS = %w[Name Type Required Description].freeze
+
+    # The ONE canonical "no value" placeholder across the whole kit — never the
+    # ASCII hyphen "-", never a bare "—" typed ad hoc in a page.
+    REQUIRED_YES = "✓"
+    REQUIRED_NO = "—"
+
+    def initialize(fields)
+      @fields = fields
+    end
+
+    def view_template
+      render DocsUI::Table.new(HEADERS, @fields.map { |field| row(field) })
+    end
+
+    private
+
+    def row(field)
+      [
+        [:code, field.fetch(:name)],
+        field.fetch(:type),
+        field.fetch(:required, false) ? REQUIRED_YES : REQUIRED_NO,
+        field.fetch(:description, REQUIRED_NO)
+      ]
+    end
+  end
+end

data/app/components/docs_ui/header.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module DocsUI
+  # A doc page header: an optional eyebrow (kicker), the title, and a lead
+  # paragraph. Gives every doc page a consistent masthead.
+  #
+  #   render DocsUI::Header.new("Installation", eyebrow: "Guide") do
+  #     plain "Add the gem and render your first component."
+  #   end
+  #
+  # The primary argument (the title) is positional, matching Section/Code and the
+  # kit-wide convention. The legacy `title:` kwarg still works so existing sites
+  # keep rendering unchanged; the positional wins if both are given.
+  class Header < Phlex::HTML
+    # Positional title (the convention), with a silent `title:` kwarg fallback for
+    # sites that still pass it by keyword. Positional wins when both are given.
+    def initialize(title = nil, eyebrow: nil, **opts)
+      @title = title || opts[:title]
+      @eyebrow = eyebrow
+    end
+
+    def view_template(&block)
+      header(class: "mb-8 border-b border-base-300 pb-6") do
+        div(class: "mb-2 text-xs font-semibold uppercase tracking-wider text-primary") { @eyebrow } if @eyebrow
+        h1(class: "text-3xl font-bold tracking-tight md:text-4xl") { @title }
+        p(class: "mt-3 text-lg text-base-content/70", &block) if block
+      end
+    end
+  end
+end

data/app/components/docs_ui/icon.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module DocsUI
+  # Renders a synced lucide icon as inline SVG via rails_icons. Thin Phlex wrapper.
+  #
+  #   render DocsUI::Icon.new("search", class: "size-4")
+  #
+  # A missing icon name falls back to a question-mark glyph outside development,
+  # rather than raising, so a typo never takes down a docs page in production.
+  class Icon < Phlex::HTML
+    MISSING_ICON = "circle-question-mark"
+
+    def initialize(name, **attributes)
+      @name = name
+      @attributes = attributes
+    end
+
+    def view_template
+      # rails_icons is a Railtie gem; outside a Rails host (isolated Phlex tests)
+      # it isn't loaded, and in a not-yet-fully-set-up app its default library may
+      # be unconfigured. Either way, render nothing rather than take down the page
+      # — icons are chrome, not content. In development we still raise so a real
+      # misconfiguration is visible.
+      return unless defined?(::Icons::Icon) && rails_icons_library
+
+      svg = svg_for(@name, **@attributes)
+      raw(safe(svg)) if svg
+    end
+
+    private
+
+    def svg_for(name, **arguments)
+      ::Icons::Icon.new(
+        name: name.to_s.dasherize,
+        library: rails_icons_library,
+        variant: nil,
+        arguments: arguments
+      ).svg
+    rescue ::Icons::IconNotFound
+      raise if local_env?
+
+      begin
+        ::Icons::Icon.new(name: MISSING_ICON, library: rails_icons_library, variant: nil, arguments: arguments).svg
+      rescue StandardError
+        nil # even the fallback glyph isn't synced — render nothing.
+      end
+    rescue StandardError
+      # Library misconfigured / icon set not synced. Surface it in dev; elsewhere
+      # degrade to no icon rather than 500 the whole docs page.
+      raise if local_env?
+
+      nil
+    end
+
+    def rails_icons_library
+      DocsKit.configuration.icon_library || ::RailsIcons.configuration.default_library
+    rescue StandardError
+      nil
+    end
+
+    def local_env?
+      defined?(Rails) && Rails.env.local?
+    end
+  end
+end

data/app/components/docs_ui/json_response.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "json"
+
+module DocsUI
+  # A pretty-printed JSON response block. Give it a Ruby Hash (deep-stringified and
+  # JSON.pretty_generate'd) or a pre-formatted String; it renders a DocsUI::Code
+  # with the json lexer and a filename title bar. Kills the hand-rolled
+  # deep_stringify + JSON.pretty_generate every API page was copy-pasting.
+  #
+  #   render DocsUI::JsonResponse.new({ id: "obj_1", status: "active" })
+  #   render DocsUI::JsonResponse.new(raw_json_string, filename: "webhook.json")
+  #
+  # A Hash with symbol keys renders as real JSON (string keys, no :symbol / =>
+  # leaking through). A String is passed through verbatim (already formatted).
+  class JsonResponse < Phlex::HTML
+    def initialize(body, filename: "response.json")
+      @body = body
+      @filename = filename
+    end
+
+    def view_template
+      render DocsUI::Code.new(json_source, lexer: :json, filename: @filename)
+    end
+
+    private
+
+    # The JSON string to highlight: a String passes through; a Hash/Array is
+    # deep-stringified then pretty-generated so it reads like an API response.
+    def json_source
+      return @body if @body.is_a?(String)
+
+      JSON.pretty_generate(deep_stringify(@body))
+    end
+
+    # Recursively stringify keys and symbol values so the output is real JSON.
+    def deep_stringify(value)
+      case value
+      when Hash then value.to_h { |k, v| [k.to_s, deep_stringify(v)] }
+      when Array then value.map { |v| deep_stringify(v) }
+      when Symbol then value.to_s
+      else value
+      end
+    end
+  end
+end