rails-ai-context 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc7244d020376cc416232a1cbbc0a287866dc4243b9566e4fa2d50d556e5a1c6
-  data.tar.gz: 5251eb33ca4d3f72803e3acc77d272a4ec038c9a367390752db463195126675a
+  metadata.gz: 6e7442b6a28d089867479cba4a99d6f0fcf64e34f692d8c47b576de8e7ec4ffd
+  data.tar.gz: 0b8b21e8c1581a056afbb03e3ef6b3c45a62c7fbb61d345bbec49d370c4fd191
 SHA512:
-  metadata.gz: ddda0c23e18344f9b95d4ff2b0e5ce9dba9c247a2915a1337226f98fb1ef2ab83b07370e2baf26bbb25261241baf75ccf40c952dd03cae4d6b6004c93398c14f
-  data.tar.gz: 790dc32dffed8275469eaebae74491dcaa0dbc2b979e53fc8e959b889c69c2eec6982304a1d0d39e22900e79a0214743cf616a8f4e70bea8a4797be679be9c9c
+  metadata.gz: e1bd3b280678917a3b94576cef271669fc6892ca32cfd522b88a4c7cee93d73d4301b6d995bd75e78fd64bb448f5e226013b8678411bfd56e68de0a59ccba35b
+  data.tar.gz: a57fed3f44c4e1599854caf8243a35f62476f487e8b14a41489bcaee1efb4e8398935211ea9073ca70f9a1e34c16a6fa13d79cdaa5cf943d6f0d5d2e82ea100c

data/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0] - 2026-03-23
+
+### Added
+
+- **Design system extraction** — ViewTemplateIntrospector now extracts canonical page examples (real HTML/ERB snippets from actual views), full color palette with semantic roles (primary/danger/success/warning), typography scale (sizes, weights, heading styles), layout patterns (containers, grids, spacing scale), responsive breakpoint usage, interactive state patterns (hover/focus/active/disabled), dark mode detection, and icon system identification.
+- **New MCP tool: `rails_get_design_system`** — dedicated tool (15th) returns the app's design system: color palette, component patterns with real HTML examples, typography, layout conventions, responsive breakpoints. Supports `detail` parameter (summary/standard/full). Total MCP tools: 15.
+- **DesignSystemHelper serializer module** — replaces flat component listings with actionable design guidance across all output formats (Claude, Cursor, Windsurf, Copilot, OpenCode). Shows components with semantic roles, canonical page examples in split rules, and explicit design rules.
+- **DesignTokenIntrospector semantic categorization** — tokens now grouped into colors/typography/spacing/sizing/borders/shadows. Enhanced Tailwind v3 parsing for fontSize, spacing, borderRadius, and screens.
+
+### Changed
+
+- **"UI Patterns" section renamed to "Design System"** — richer content with color palette, typography, components, spacing conventions, interactive states, and design rules.
+- **Design tokens consumed for the first time** — `context[:design_tokens]` data was previously extracted but never rendered. Now merged into design system output in all serializers and the new MCP tool.
+
 ## [1.1.1] - 2026-03-23
 
 ### Added

data/CLAUDE.md

@@ -9,7 +9,7 @@ structure to AI assistants via the Model Context Protocol (MCP).
 - `lib/rails_ai_context/configuration.rb` — User-facing config with presets (:standard, :full)
 - `lib/rails_ai_context/introspector.rb` — Orchestrates sub-introspectors
 - `lib/rails_ai_context/introspectors/` — 29 introspectors (schema, models, routes, jobs, gems, conventions, stimulus, database_stats, controllers, views, view_templates, design_tokens, turbo, i18n, config, active_storage, action_text, auth, api, tests, rake_tasks, assets, devops, action_mailbox, migrations, seeds, middleware, engines, multi_database)
-- `lib/rails_ai_context/tools/` — 14 MCP tools using the official mcp SDK
+- `lib/rails_ai_context/tools/` — 15 MCP tools using the official mcp SDK
 - `lib/rails_ai_context/serializers/` — Output formatters (claude, claude_rules, opencode, opencode_rules, cursor_rules, windsurf, windsurf_rules, copilot, copilot_instructions, rules, markdown, JSON, context_file_serializer, test_command_detection)
 - `lib/rails_ai_context/resources.rb` — MCP resources (static data AI clients read directly)
 - `lib/rails_ai_context/server.rb` — MCP server configuration (stdio + HTTP transports)
@@ -39,7 +39,8 @@ structure to AI assistants via the Model Context Protocol (MCP).
 13. **Per-tool split rules** — `.claude/rules/`, `.cursor/rules/`, `.windsurf/rules/`, `.github/instructions/`
 14. **Section markers** — root file content wrapped in `<!-- BEGIN/END rails-ai-context -->` to preserve user content
 15. **generate_root_files toggle** — when false, skip root files (CLAUDE.md, etc.), only generate split rules
-16. **custom_tools API** — `config.custom_tools` array lets users register additional MCP::Tool subclasses alongside the 14 built-in tools
+16. **custom_tools API** — `config.custom_tools` array lets users register additional MCP::Tool subclasses alongside the 15 built-in tools
+17. **Design system extraction** — view templates analyzed for canonical examples, color palette, typography, responsive patterns, interactive states, dark mode
 
 ## Testing
 

data/SECURITY.md

@@ -4,6 +4,7 @@
 
 | Version | Supported          |
 |---------|--------------------|
+| 1.2.x   | :white_check_mark: |
 | 1.1.x    | :white_check_mark: |
 | 1.0.x   | :white_check_mark: |
 | < 1.0   | :x:                |

data/lib/rails_ai_context/introspectors/design_token_introspector.rb

@@ -37,7 +37,8 @@ module RailsAiContext
 
         {
           framework: detect_framework(root),
-          tokens: tokens
+          tokens: tokens,
+          categorized: categorize_tokens(tokens)
         }
       rescue => e
         { error: e.message }
@@ -116,6 +117,34 @@ module RailsAiContext
         content.scan(/(\w+)\s*:\s*\[['"]([^'"]+)['"]/).each do |name, font|
           tokens["tw3-font-#{name}"] = font if name.match?(/font|sans|serif|mono|display|heading/)
         end
+
+        # Extract fontSize configuration
+        content.scan(/fontSize\s*:\s*\{([^}]+)\}/m).each do |match|
+          match[0].scan(/['"]([\w-]+)['"]\s*:\s*['"]([^'"]+)['"]/).each do |name, value|
+            tokens["tw3-fontSize-#{name}"] = value
+          end
+        end
+
+        # Extract screens (breakpoints)
+        content.scan(/screens\s*:\s*\{([^}]+)\}/m).each do |match|
+          match[0].scan(/['"]([\w-]+)['"]\s*:\s*['"]([^'"]+)['"]/).each do |name, value|
+            tokens["tw3-screen-#{name}"] = value
+          end
+        end
+
+        # Extract spacing overrides
+        content.scan(/spacing\s*:\s*\{([^}]+)\}/m).each do |match|
+          match[0].scan(/['"]([\w.-]+)['"]\s*:\s*['"]([^'"]+)['"]/).each do |name, value|
+            tokens["tw3-spacing-#{name}"] = value
+          end
+        end
+
+        # Extract borderRadius overrides
+        content.scan(/borderRadius\s*:\s*\{([^}]+)\}/m).each do |match|
+          match[0].scan(/['"]([\w-]+)['"]\s*:\s*['"]([^'"]+)['"]/).each do |name, value|
+            tokens["tw3-radius-#{name}"] = value
+          end
+        end
       end
 
       # 4. Bootstrap/Sass variable definitions
@@ -174,6 +203,41 @@ module RailsAiContext
         end
       end
 
+      def categorize_tokens(tokens)
+        categories = {
+          colors: {},
+          typography: {},
+          spacing: {},
+          sizing: {},
+          borders: {},
+          shadows: {},
+          other: {}
+        }
+
+        tokens.each do |name, value|
+          category = case name
+          when /color|brand|primary|secondary|danger|success|warning|accent|neutral|bg|surface/i
+            :colors
+          when /font|text-size|leading|tracking|letter-spacing|line-height/i
+            :typography
+          when /spacing|gap|margin|padding|space|inset/i
+            :spacing
+          when /width|height|size|radius|rounded|screen|breakpoint/i
+            :sizing
+          when /border|ring|outline|divide/i
+            :borders
+          when /shadow/i
+            :shadows
+          else
+            name.match?(/shade-\d+|#[\da-fA-F]/) ? :colors : :other
+          end
+
+          categories[category][name] = value
+        end
+
+        categories.reject { |_, v| v.empty? }
+      end
+
       # Helper: extract :root { --var: value } from CSS content
       def extract_root_vars(content, tokens)
         content.scan(/:root\s*(?:,\s*:host)?\s*\{([^}]+)\}/m).each do |match|

data/lib/rails_ai_context/introspectors/view_template_introspector.rb

@@ -20,7 +20,9 @@ module RailsAiContext
         {
           templates: scan_templates(views_dir),
           partials: scan_partials(views_dir),
-          ui_patterns: extract_ui_patterns(all_content)
+          ui_patterns: extract_ui_patterns(all_content).merge(
+            canonical_examples: extract_canonical_examples(views_dir)
+          )
         }
       rescue => e
         { error: e.message }
@@ -106,7 +108,13 @@ module RailsAiContext
           color_scheme: color_scheme,
           radius: radius_convention,
           form_layout: form_layout,
-          components: components
+          components: components,
+          typography: extract_typography(all_content),
+          layout: extract_layout_patterns(all_content),
+          responsive: extract_responsive_patterns(all_content),
+          interactive_states: extract_interactive_states(all_content),
+          dark_mode: extract_dark_mode_patterns(all_content),
+          icons: extract_icon_system(all_content)
         }
       end
 
@@ -149,12 +157,19 @@ module RailsAiContext
             "primary"
           end
           next unless role # skip unclassified buttons
-          classified[role] = { classes: c, count: count } if !classified[role] || count > classified[role][:count]
+          classified[role] ||= { classes: c, count: count, variants: [] }
+          classified[role][:variants] << { classes: c, count: count }
+          if count > classified[role][:count]
+            classified[role][:classes] = c
+            classified[role][:count] = count
+          end
         end
 
         classified.each do |role, data|
           label = role == "default" ? "Button" : "Button (#{role})"
-          components << { type: :button, label: label, classes: data[:classes] }
+          entry = { type: :button, label: label, classes: data[:classes] }
+          entry[:variants] = data[:variants] if data[:variants]&.size&.> 1
+          components << entry
           used << data[:classes]
         end
       end
@@ -287,7 +302,7 @@ module RailsAiContext
         components << { type: :alert, label: "Alert", classes: best[0] }
       end
 
-      def extract_color_scheme(_content, groups)
+      def extract_color_scheme(content, groups)
         # Find primary color from button backgrounds
         primary_colors = Hash.new(0)
         groups.each do |c, count|
@@ -306,6 +321,27 @@ module RailsAiContext
         scheme = {}
         scheme[:primary] = primary if primary
         scheme[:text] = text_colors.join("/") if text_colors.any?
+
+        # Full palette: background colors used
+        bg_colors = Hash.new(0)
+        content.scan(/bg-(\w+)-(\d+)/).each { |color, shade| bg_colors["#{color}-#{shade}"] += 1 }
+        scheme[:background_palette] = bg_colors.sort_by { |_, c| -c }.first(10).map(&:first) if bg_colors.any?
+
+        # Text color palette
+        text_palette = Hash.new(0)
+        content.scan(/text-(\w+)-(\d+)/).each { |color, shade| text_palette["#{color}-#{shade}"] += 1 }
+        scheme[:text_palette] = text_palette.sort_by { |_, c| -c }.first(8).map(&:first) if text_palette.any?
+
+        # Border color palette
+        border_colors = Hash.new(0)
+        content.scan(/border-(\w+)-(\d+)/).each { |color, shade| border_colors["#{color}-#{shade}"] += 1 }
+        scheme[:border_palette] = border_colors.sort_by { |_, c| -c }.first(5).map(&:first) if border_colors.any?
+
+        # Semantic roles inferred from usage
+        scheme[:danger] = "red" if bg_colors.any? { |k, _| k.start_with?("red-") }
+        scheme[:success] = "green" if bg_colors.any? { |k, _| k.start_with?("green-") }
+        scheme[:warning] = "yellow" if bg_colors.any? { |k, _| k.start_with?("yellow-") || k.start_with?("amber-") }
+
         scheme
       end
 
@@ -332,6 +368,179 @@ module RailsAiContext
         layout
       end
 
+      def extract_responsive_patterns(content)
+        breakpoints = {}
+        %w[sm md lg xl 2xl].each do |bp|
+          matches = content.scan(/#{bp}:[\w-]+/).map { |m| m.sub("#{bp}:", "") }
+          next if matches.empty?
+          breakpoints[bp] = matches.tally.sort_by { |_, c| -c }.first(5).to_h
+        end
+        breakpoints
+      end
+
+      def extract_interactive_states(content)
+        states = {}
+        %w[hover focus active disabled group-hover focus-within focus-visible].each do |state|
+          matches = content.scan(/#{state}:[\w-]+/)
+          next if matches.empty?
+          states[state] = matches.tally.sort_by { |_, c| -c }.first(5).to_h
+        end
+        states
+      end
+
+      def extract_dark_mode_patterns(content)
+        dark_classes = content.scan(/dark:[\w-]+/)
+        return {} if dark_classes.empty?
+        { used: true, patterns: dark_classes.tally.sort_by { |_, c| -c }.first(10).to_h }
+      end
+
+      def extract_layout_patterns(content)
+        layout = {}
+
+        containers = content.scan(/(?:max-w-\w+|container)\b/).tally
+        layout[:containers] = containers.sort_by { |_, c| -c }.first(3).to_h unless containers.empty?
+
+        flex = content.scan(/(?:flex-(?:row|col|wrap)|items-\w+|justify-\w+)\b/).tally
+        layout[:flex] = flex.sort_by { |_, c| -c }.first(5).to_h unless flex.empty?
+
+        grids = content.scan(/grid-cols-\d+/).tally
+        layout[:grid] = grids.sort_by { |_, c| -c }.first(3).to_h unless grids.empty?
+
+        spacing = content.scan(/(?:space-[xy]-|gap-|p-|px-|py-|m-|mx-|my-|mt-|mb-)\d+/).tally
+        layout[:spacing_scale] = spacing.sort_by { |_, c| -c }.first(8).to_h unless spacing.empty?
+
+        layout
+      end
+
+      def extract_typography(content)
+        typo = {}
+
+        sizes = content.scan(/text-(?:xs|sm|base|lg|xl|2xl|3xl|4xl|5xl|6xl)/).tally
+        typo[:sizes] = sizes.sort_by { |_, c| -c }.to_h unless sizes.empty?
+
+        weights = content.scan(/font-(?:thin|extralight|light|normal|medium|semibold|bold|extrabold|black)/).tally
+        typo[:weights] = weights.sort_by { |_, c| -c }.to_h unless weights.empty?
+
+        headings = {}
+        %w[h1 h2 h3 h4].each do |tag|
+          classes = content.scan(/<#{tag}[^>]*class=["']([^"']+)["']/i).map { |m| m[0].gsub(/<%=.*?%>/, "").strip }
+          next if classes.empty?
+          headings[tag] = classes.tally.max_by { |_, c| c }[0]
+        end
+        typo[:heading_styles] = headings unless headings.empty?
+
+        leading = content.scan(/leading-\w+/).tally
+        typo[:line_height] = leading.sort_by { |_, c| -c }.first(3).to_h unless leading.empty?
+
+        typo
+      end
+
+      def extract_icon_system(content)
+        icons = {}
+
+        icons[:library] = "heroicons" if content.match?(/heroicon|hero_icon/)
+        icons[:library] = "lucide" if content.match?(/lucide|data-lucide/)
+        icons[:library] = "font-awesome" if content.match?(/fa-\w+|font-awesome/)
+        icons[:library] = "bootstrap-icons" if content.match?(/bi-\w+/)
+
+        svg_count = content.scan(/<svg\b/).size
+        icons[:inline_svg_count] = svg_count if svg_count > 0
+
+        icon_sizes = content.scan(/(?:w-\d+\s+h-\d+|size-\d+)/).tally
+        icons[:sizes] = icon_sizes.sort_by { |_, c| -c }.first(3).to_h unless icon_sizes.empty?
+
+        icons.empty? ? nil : icons
+      end
+
+      # Analyzes individual templates to find canonical examples of common page types.
+      # Returns up to 5 representative ERB snippets that AI can copy.
+      def extract_canonical_examples(views_dir) # rubocop:disable Metrics
+        max_snippet = 80 # lines per example
+        max_file = RailsAiContext.configuration.max_view_file_size
+        examples = {}
+
+        Dir.glob(File.join(views_dir, "**", "*.{erb,haml,slim}")).each do |path|
+          next if File.directory?(path)
+          next if File.basename(path).start_with?("_") # skip partials
+          next if path.include?("/layouts/")
+          next if File.size(path) > max_file
+
+          relative = path.sub("#{views_dir}/", "")
+          content = File.read(path, encoding: "UTF-8", invalid: :replace, undef: :replace) rescue next
+
+          page_type = classify_template(content)
+          next unless page_type
+
+          score = score_template(content)
+          existing = examples[page_type]
+
+          if !existing || score > existing[:score]
+            snippet = content.lines.first(max_snippet).join
+            # Strip large SVG blocks
+            snippet = snippet.gsub(/<svg[^>]*>.*?<\/svg>/m, "<!-- svg icon -->")
+            components_used = detect_components_in_template(content)
+
+            examples[page_type] = {
+              type: page_type,
+              template: relative,
+              snippet: snippet,
+              components_used: components_used,
+              score: score
+            }
+          end
+        end
+
+        examples.values.map { |e| e.except(:score) }.first(5)
+      rescue
+        []
+      end
+
+      def classify_template(content)
+        has_form = content.match?(/form_with|form_for|<form\b/i)
+        has_collection = content.match?(/\.each\s+do\b|render\s+collection:|render\s+@\w+/)
+        has_grid = content.match?(/grid-cols-|grid\s+grid-/)
+        has_show = content.match?(/\A(?:(?!\.each).)*@\w+\.\w+/m) && !has_collection
+
+        if has_form && !has_collection
+          :form_page
+        elsif has_collection || has_grid
+          :list_page
+        elsif has_show
+          :show_page
+        end
+      end
+
+      def score_template(content)
+        score = 0
+        # Prefer templates with more design patterns
+        score += content.scan(/class=["'][^"']+["']/).size.clamp(0, 20)
+        # Responsive classes
+        score += 5 if content.match?(/(?:sm|md|lg|xl):/)
+        # Interactive states
+        score += 3 if content.match?(/hover:|focus:/)
+        # Component variety
+        score += 2 if content.match?(/<button|btn/i)
+        score += 2 if content.match?(/shadow.*rounded|card/i)
+        score += 2 if content.match?(/<input|form_with|form_for/i)
+        # Not too short, not too long (sweet spot: 30-100 lines)
+        lines = content.lines.size
+        score += 5 if lines.between?(30, 100)
+        score -= 3 if lines < 10
+        score
+      end
+
+      def detect_components_in_template(content)
+        used = []
+        used << :button if content.match?(/bg-\w+-[5-9]00.*text-white|btn-|<button/i)
+        used << :card if content.match?(/shadow.*rounded|card/i)
+        used << :input if content.match?(/<input|text_field|email_field|password_field/i)
+        used << :form if content.match?(/form_with|form_for|<form/i)
+        used << :link if content.match?(/link_to|<a\b/i)
+        used << :badge if content.match?(/rounded-full.*text-(?:xs|sm)|badge/i)
+        used << :grid if content.match?(/grid-cols-|grid\s+grid-/)
+        used
+      end
+
       EXCLUDED_METHODS = %w[
         each map select reject first last size count any? empty? present? blank?
         new build create find where order limit nil? join class html_safe

data/lib/rails_ai_context/serializers/claude_rules_serializer.rb

@@ -6,6 +6,7 @@ module RailsAiContext
     # These provide quick-reference lists without bloating CLAUDE.md.
     class ClaudeRulesSerializer
       include StackOverviewHelper
+      include DesignSystemHelper
 
       attr_reader :context
 
@@ -250,31 +251,10 @@ module RailsAiContext
         components = patterns[:components] || []
         return nil if components.empty?
 
-        lines = [ "# UI Patterns", "" ]
+        lines = [ "# Design System", "" ]
 
-        scheme = patterns[:color_scheme] || {}
-        parts = []
-        parts << "Primary: #{scheme[:primary]}" if scheme[:primary]
-        parts << "Text: #{scheme[:text]}" if scheme[:text]
-        lines << parts.join(" | ") if parts.any?
-
-        radius = patterns[:radius] || {}
-        if radius.any?
-          # Group by radius value to avoid repetition
-          by_radius = radius.group_by { |_, r| r }.map { |r, types| "#{r} (#{types.map(&:first).join(', ')})" }
-          lines << "Radius: #{by_radius.join(', ')}"
-        end
-        lines << ""
-
-        lines << "## Components"
-        components.first(20).each { |c| next unless c[:label] && c[:classes]; lines << "- #{c[:label]}: `#{c[:classes]}`" }
-
-        fl = patterns[:form_layout] || {}
-        if fl.any?
-          lines << "" << "## Form layout"
-          lines << "- Spacing: #{fl[:spacing]}" if fl[:spacing]
-          lines << "- Grid: #{fl[:grid]}" if fl[:grid]
-        end
+        # Full design system with canonical examples
+        lines.concat(render_design_system_full(context))
 
         # Shared partials — so agents reuse them instead of recreating
         begin
@@ -346,7 +326,7 @@ module RailsAiContext
           "- app/javascript/controllers/index.js — Stimulus auto-registers controllers. No need to read.",
           "- Test files — use `rails_get_test_info(detail:\"full\")` for patterns.",
           "",
-          "## Tools (14)",
+          "## Tools (15)",
           "",
           "**rails_get_schema** — database tables, columns, indexes, foreign keys",
           "- `rails_get_schema(detail:\"summary\")` — all tables with column counts",
@@ -387,6 +367,10 @@ module RailsAiContext
           "**rails_analyze_feature** — combined schema + models + controllers + routes for a feature area",
           "- `rails_analyze_feature(feature:\"authentication\")` — one call gets everything related to a feature",
           "",
+          "**rails_get_design_system** — color palette, component patterns, canonical page examples",
+          "- `rails_get_design_system(detail:\"standard\")` — colors + components + real HTML examples + design rules",
+          "- `rails_get_design_system(detail:\"full\")` — + typography, responsive, dark mode, layout, spacing",
+          "",
           "**rails_get_config** — cache store, session, timezone, middleware, initializers",
           "**rails_get_gems** — notable gems categorized by function",
           "**rails_get_conventions** — architecture patterns, directory structure",

data/lib/rails_ai_context/serializers/claude_serializer.rb

@@ -8,6 +8,7 @@ module RailsAiContext
     class ClaudeSerializer
       include TestCommandDetection
       include StackOverviewHelper
+      include DesignSystemHelper
 
       attr_reader :context
 
@@ -192,40 +193,12 @@ module RailsAiContext
       end
 
       def render_ui_patterns
-        vt = context[:view_templates]
-        return [] unless vt.is_a?(Hash) && !vt[:error]
-        patterns = vt[:ui_patterns] || {}
-        components = patterns[:components] || []
-        return [] if components.empty?
-
-        lines = [ "## UI Patterns" ]
-
-        # Color scheme summary
-        scheme = patterns[:color_scheme] || {}
-        if scheme.any?
-          parts = []
-          parts << "Primary: #{scheme[:primary]}" if scheme[:primary]
-          parts << "Text: #{scheme[:text]}" if scheme[:text]
-          lines << parts.join(" | ") if parts.any?
-        end
-
-        lines << ""
-        components.first(15).each do |comp|
-          lines << "- #{comp[:label]}: `#{comp[:classes]}`"
-        end
-
-        # Form layout
-        fl = patterns[:form_layout] || {}
-        if fl.any?
-          lines << "" << "Form: #{fl.values.join(', ')}"
-        end
-        lines << ""
-        lines
+        render_design_system(context, max_lines: 30)
       end
 
       def render_mcp_guide # rubocop:disable Metrics/MethodLength
         [
-          "## MCP Tools (14) — ALWAYS Use These First",
+          "## MCP Tools (15) — ALWAYS Use These First",
           "",
           "Use MCP for reference files (schema, routes, tests). Read directly if you'll edit.",
           "MCP tools return line numbers. Start with `detail:\"summary\"`.",
@@ -238,6 +211,7 @@ module RailsAiContext
           "- `rails_get_stimulus(detail:\"summary\")` → `(controller:\"name\")` — targets, actions, values",
           "- `rails_get_test_info(detail:\"full\")` — fixtures, factories, helpers; `(model:\"Cook\")` — tests",
           "- `rails_analyze_feature(feature:\"auth\")` — schema + models + controllers + routes for a feature",
+          "- `rails_get_design_system` — color palette, component patterns, canonical page examples",
           "- `rails_get_config` | `rails_get_gems` | `rails_get_conventions` | `rails_search_code`",
           "- `rails_validate(files:[\"path/to/file.rb\"])` — validate Ruby, ERB, JS syntax in one call",
           ""

data/lib/rails_ai_context/serializers/copilot_instructions_serializer.rb

@@ -6,6 +6,7 @@ module RailsAiContext
     # for GitHub Copilot path-specific instructions.
     class CopilotInstructionsSerializer
       include StackOverviewHelper
+      include DesignSystemHelper
 
       attr_reader :context
 
@@ -193,37 +194,10 @@ module RailsAiContext
           "---",
           "applyTo: \"app/views/**/*.erb\"",
           "---",
-          "",
-          "# UI Patterns",
           ""
         ]
-        components.first(15).each { |c| next unless c[:label] && c[:classes]; lines << "- #{c[:label]}: `#{c[:classes]}`" }
-
-        # Shared partials
-        begin
-          root = defined?(Rails) ? Rails.root.to_s : Dir.pwd
-          shared_dir = File.join(root, "app", "views", "shared")
-          if Dir.exist?(shared_dir)
-            partials = Dir.glob(File.join(shared_dir, "_*.html.erb")).map { |f| File.basename(f) }.sort
-            if partials.any?
-              lines << "" << "## Shared partials"
-              partials.each { |p| lines << "- #{p}" }
-            end
-          end
-        rescue; end
 
-        # Helpers
-        begin
-          root = defined?(Rails) ? Rails.root.to_s : Dir.pwd
-          helper_file = File.join(root, "app", "helpers", "application_helper.rb")
-          if File.exist?(helper_file)
-            helper_methods = File.read(helper_file).scan(/def\s+(\w+)/).flatten
-            if helper_methods.any?
-              lines << "" << "## Helpers (ApplicationHelper)"
-              helper_methods.each { |m| lines << "- #{m}" }
-            end
-          end
-        rescue; end
+        lines.concat(render_design_system_full(context))
 
         # Stimulus controllers
         stim = context[:stimulus]
@@ -245,7 +219,7 @@ module RailsAiContext
           "applyTo: \"**/*\"",
           "---",
           "",
-          "# Rails MCP Tools (14) — Use These First",
+          "# Rails MCP Tools (15) — Use These First",
           "",
           "Use MCP for reference files (schema, routes, tests). Read directly if you'll edit.",
           "MCP tools return line numbers for surgical edits.",
@@ -259,6 +233,7 @@ module RailsAiContext
           "- `rails_get_stimulus(detail:\"summary\")` → `(controller:\"name\")` — targets, actions, values",
           "- `rails_get_test_info(detail:\"full\")` — fixtures, factories, helpers; `(model:\"Cook\")` — existing tests",
           "- `rails_analyze_feature(feature:\"auth\")` — schema + models + controllers + routes for a feature",
+          "- `rails_get_design_system` — color palette, components, canonical page examples",
           "- `rails_get_config` | `rails_get_gems` | `rails_get_conventions` | `rails_search_code`",
           "- `rails_get_edit_context(file:\"path\", near:\"keyword\")` — surgical edit context with line numbers",
           "- `rails_validate(files:[\"path\"])` — validate Ruby, ERB, JS syntax in one call",

data/lib/rails_ai_context/serializers/copilot_serializer.rb

@@ -8,6 +8,7 @@ module RailsAiContext
     class CopilotSerializer
       include TestCommandDetection
       include StackOverviewHelper
+      include DesignSystemHelper
 
       attr_reader :context
 
@@ -87,16 +88,8 @@ module RailsAiContext
           end
         end
 
-        # UI Patterns
-        vt = context[:view_templates]
-        if vt.is_a?(Hash) && !vt[:error]
-          components = vt.dig(:ui_patterns, :components) || []
-          if components.any?
-            lines << "## UI Patterns"
-            components.first(15).each { |c| next unless c[:label] && c[:classes]; lines << "- #{c[:label]}: `#{c[:classes]}`" }
-            lines << ""
-          end
-        end
+        # Design System
+        lines.concat(render_design_system(context, max_lines: 35))
 
         # MCP tools
         lines << "## MCP Tool Reference"