rails-design-profiles 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f94b1e0af567ce077819a716dc34eb34462542a7bf251cdbb287376fcc7ee3e6
+  data.tar.gz: 9c96463447b584330e2e09d95da375b5c96ddc3fad795536a936feb2d584c5c0
+SHA512:
+  metadata.gz: 14674431eac89956035122bc7a4a1941258ca2248b76d2d9bc173df3592defd327c722f7ae517c101cbf5a6f954f9072f2601f9a4fffcc3c9ae97c69741a06d6
+  data.tar.gz: ca65b17b242bc0805a8dda7f69716ecbb85d30b17e2515ade2ea9223ccc753d844552e0c64103569ee32d8b50c5ec594f83cd4429ae721cd9c729d24bc497a2c

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.1 - 2026-07-17
+
+- Refresh project documentation, community materials, GitHub Pages, and CI compatibility.
+
+## 0.1.0 - 2026-07-16
+
+- Initial release with Rails helper, profile configuration, generators, and public reference tasks.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,4 @@
+# Contributor Covenant Code of Conduct
+
+Contributors are expected to be respectful, constructive, and inclusive. Harassment or discriminatory behavior is not tolerated. Report concerns privately to fnpaladini@gmail.com.
+

data/CONTRIBUTING.md

@@ -0,0 +1,23 @@
+# Contributing
+
+Thank you for helping make Rails interfaces more intentional and more maintainable.
+
+## Before you start
+
+- Use [Discussions](https://github.com/paladini/rails-design-profiles/discussions) for questions and proposals; open an issue when you have a reproducible bug or a focused feature.
+- Keep pull requests narrow. Discuss changes that alter public configuration, task names, or output first.
+- Never submit copied third-party CSS, assets, logos, or proprietary `DESIGN.md` content. References are context; executable tokens are authored and reviewed by the application team.
+
+## Local workflow
+
+```sh
+bundle install
+bundle exec rake test
+gem build rails-design-profiles.gemspec
+```
+
+The CI suite verifies Ruby 3.1 with Rails 7.1 and current supported Ruby versions. Add a regression test for each behavior change and update the README when a public command, configuration key, or output changes.
+
+## Pull requests
+
+Explain the user problem, the chosen behavior, and how you verified it. Maintainers prioritize correctness, small APIs, accessible output, and changes that preserve the distinction between a design reference and a production theme.

data/LICENSE.txt

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Fernando Paladini
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/README.md

@@ -0,0 +1,136 @@
+# rails-design-profiles
+
+[![CI](https://github.com/paladini/rails-design-profiles/actions/workflows/ci.yml/badge.svg)](https://github.com/paladini/rails-design-profiles/actions/workflows/ci.yml)
+[![RubyGems](https://img.shields.io/gem/v/rails-design-profiles?logo=rubygems&label=RubyGems)](https://rubygems.org/gems/rails-design-profiles)
+[![License](https://img.shields.io/github/license/paladini/rails-design-profiles)](LICENSE.txt)
+
+**A design reference should influence your Rails UI without becoming an unreviewable theme generator.**
+
+`rails-design-profiles` keeps the two jobs separate:
+
+1. `DESIGN.md` gives your AI agent a clear visual reference.
+2. A small YAML profile exposes the tokens your Rails application actually uses.
+
+The result is a deliberate CSS-variable contract you can review, version, switch, and evolve with your team.
+
+## Why this exists
+
+AI can read a `DESIGN.md`, but Markdown alone does not change an application. Conversely, replacing an entire stylesheet to try a visual direction is risky and hard to review.
+
+This gem gives Rails applications a narrow bridge between the two: references stay local and explicit; CSS variables are emitted from an active profile; your components decide which tokens to consume.
+
+## Install
+
+```ruby
+# Gemfile
+gem "rails-design-profiles"
+```
+
+```sh
+bundle install
+bin/rails generate rails_design_profiles:install
+```
+
+The generator adds a profile file and inserts the helper into `app/views/layouts/application.html.erb`:
+
+```erb
+<%= rails_design_profiles_tags %>
+```
+
+Use the resulting variables in your own CSS:
+
+```css
+body {
+  color: var(--rdp-color-text);
+  background: var(--rdp-color-surface);
+  font-family: var(--rdp-font-body);
+}
+
+.button {
+  background: var(--rdp-color-primary);
+  padding: var(--rdp-space-page);
+}
+```
+
+## The profile contract
+
+`config/design_profiles.yml` is the source of truth for production tokens. Token names become `--rdp-*` CSS variables.
+
+```yaml
+active: editorial
+profiles:
+  editorial:
+    reference: config/design_profiles/references/claude.md
+    tokens:
+      color-primary: "#c15f3c"
+      color-surface: "#f8f6f2"
+      color-text: "#24211e"
+      font-body: "Newsreader, Georgia, serif"
+      space-page: "1.5rem"
+```
+
+The active profile is global to the app and is resolved for every response. Version 0.1 does not include per-session or query-string overrides.
+
+## Bring a public reference into your project
+
+The v0.1 catalog uses only the MIT-licensed [VoltAgent/awesome-design-md](https://github.com/VoltAgent/awesome-design-md) collection.
+
+```sh
+bin/rails design:list
+bin/rails design:install[claude]
+```
+
+Installation stores the reference in `config/design_profiles/references/claude.md` and creates an empty `claude` profile. Read that reference with your agent, choose the tokens that fit your product, and add them deliberately to YAML.
+
+Switch profiles with:
+
+```sh
+bin/rails design:activate[claude]
+```
+
+The gem never copies third-party CSS, assets, or branding. It is not affiliated with getdesign.md, VoltAgent, or any referenced brand.
+
+## How it works
+
+```text
+DESIGN.md reference ──> team / AI design decisions ──> design_profiles.yml
+                                                            │
+                                                            ▼
+                                              <style> --rdp-* variables
+                                                            │
+                                                            ▼
+                                                   your Rails components
+```
+
+This is intentionally not a Markdown-to-CSS compiler. It preserves human judgment at the point where visual decisions become production code.
+
+## Compatibility
+
+- Ruby 3.1+
+- Rails 7.1+
+- Asset pipeline, Propshaft, Importmap, Tailwind, and custom CSS all work because the output is standard CSS variables.
+
+## Community
+
+- Ask questions and share workflows in [Discussions](https://github.com/paladini/rails-design-profiles/discussions).
+- Report reproducible defects or focused feature requests through the issue templates.
+- Read [CONTRIBUTING.md](CONTRIBUTING.md), [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md), [SUPPORT.md](SUPPORT.md), and [SECURITY.md](SECURITY.md) before participating.
+
+### Roadmap
+
+- [ ] Profile validation and diagnostics
+- [ ] A profile preview surface for development
+- [ ] More import adapters for openly licensed design references
+- [ ] Community-maintained example Rails applications
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test
+gem build rails-design-profiles.gemspec
+```
+
+## License
+
+MIT. See [LICENSE.txt](LICENSE.txt).

data/lib/generators/rails_design_profiles/install/install_generator.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+
+module RailsDesignProfiles
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def create_configuration
+        template "design_profiles.yml", "config/design_profiles.yml" unless File.exist?(path("config/design_profiles.yml"))
+      end
+
+      def add_style_helper_to_layout
+        layout = "app/views/layouts/application.html.erb"
+        return unless File.exist?(path(layout))
+        return if File.read(path(layout)).include?("rails_design_profiles_tags")
+
+        inject_into_file layout, "    <%= rails_design_profiles_tags %>\n", before: "  </head>\n"
+      end
+
+      private
+
+      def path(relative_path)
+        File.join(destination_root, relative_path)
+      end
+    end
+  end
+end

data/lib/generators/rails_design_profiles/install/templates/design_profiles.yml

@@ -0,0 +1,12 @@
+# CSS values are intentionally explicit and reviewable. Reference files are context for AI agents.
+active: default
+profiles:
+  default:
+    reference: null
+    tokens:
+      color-primary: "#2563eb"
+      color-surface: "#ffffff"
+      color-text: "#111827"
+      font-body: "system-ui, sans-serif"
+      space-page: "1.5rem"
+

data/lib/rails_design_profiles/catalog_client.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "uri"
+
+module RailsDesignProfiles
+  class CatalogClient
+    REPOSITORY = "VoltAgent/awesome-design-md"
+    TREE_URL = "https://api.github.com/repos/#{REPOSITORY}/git/trees/main?recursive=1"
+    RAW_URL = "https://raw.githubusercontent.com/#{REPOSITORY}/main/design-md/%<slug>s/DESIGN.md"
+
+    def initialize(http_get: nil)
+      @http_get = http_get || method(:get)
+    end
+
+    def slugs
+      tree = JSON.parse(@http_get.call(TREE_URL)).fetch("tree")
+      tree.filter_map { |entry| entry.fetch("path")[%r{\Adesign-md/([^/]+)/DESIGN\.md\z}, 1] }.sort
+    rescue JSON::ParserError, KeyError => error
+      raise CatalogError, "Unexpected catalog response: #{error.message}"
+    end
+
+    def download(slug)
+      validate_slug!(slug)
+      @http_get.call(format(RAW_URL, slug: slug))
+    end
+
+    private
+
+    def get(url)
+      uri = URI(url)
+      response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: 5, read_timeout: 10) do |http|
+        http.get(uri.request_uri, "User-Agent" => "rails-design-profiles/#{VERSION}")
+      end
+      return response.body if response.is_a?(Net::HTTPSuccess)
+
+      raise CatalogError, "Catalog request failed (HTTP #{response.code})"
+    rescue SocketError, Timeout::Error, Errno::ECONNREFUSED => error
+      raise CatalogError, "Catalog request failed: #{error.message}"
+    end
+
+    def validate_slug!(slug)
+      return if slug.is_a?(String) && slug.match?(/\A[a-z0-9]+(?:-[a-z0-9]+)*\z/)
+
+      raise CatalogError, "Invalid catalog slug: #{slug.inspect}"
+    end
+  end
+end
+

data/lib/rails_design_profiles/helper.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module RailsDesignProfiles
+  module Helper
+    def rails_design_profiles_tags
+      css = RailsDesignProfiles.store.css_variables
+      return "".html_safe if css.empty?
+
+      content_tag(:style, ":root {#{css}}".html_safe, id: "rails-design-profiles")
+    end
+  end
+end
+

data/lib/rails_design_profiles/profile_store.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "yaml"
+
+module RailsDesignProfiles
+  class ProfileStore
+    CONFIG_PATH = "config/design_profiles.yml"
+
+    def initialize(root)
+      @root = Pathname(root)
+    end
+
+    def active_profile
+      profile_named(data.fetch("active"))
+    rescue KeyError
+      raise ConfigurationError, "Missing active profile in #{config_path}"
+    end
+
+    def css_variables
+      tokens = active_profile.fetch("tokens", {})
+      unless tokens.is_a?(Hash)
+        raise ConfigurationError, "Profile tokens must be a mapping in #{config_path}"
+      end
+
+      tokens.filter_map do |name, value|
+        next unless valid_token?(name, value)
+
+        "--rdp-#{name}: #{value};"
+      end.join
+    end
+
+    def install_reference!(slug, contents)
+      validate_slug!(slug)
+      reference_path = references_path.join("#{slug}.md")
+      raise ConfigurationError, "Reference already exists: #{reference_path}" if reference_path.exist?
+
+      config = data
+      profiles = config.fetch("profiles")
+      if profiles.key?(slug)
+        raise ConfigurationError, "Profile already exists: #{slug}"
+      end
+
+      FileUtils.mkdir_p(reference_path.dirname)
+      reference_path.write(contents)
+      profiles[slug] = {
+        "reference" => reference_path.relative_path_from(@root).to_s,
+        "tokens" => {}
+      }
+      write(config)
+    rescue StandardError
+      FileUtils.rm_f(reference_path) if defined?(reference_path) && reference_path&.exist?
+      raise
+    end
+
+    def activate!(name)
+      config = data
+      profile_named(name, config)
+      config["active"] = name
+      write(config)
+    end
+
+    private
+
+    def data
+      raise ConfigurationError, "Missing configuration: #{config_path}" unless config_path.exist?
+
+      parsed = YAML.safe_load(config_path.read, permitted_classes: [], aliases: false)
+      unless parsed.is_a?(Hash) && parsed["profiles"].is_a?(Hash)
+        raise ConfigurationError, "Expected active and profiles mappings in #{config_path}"
+      end
+
+      parsed
+    rescue Psych::Exception => error
+      raise ConfigurationError, "Invalid YAML in #{config_path}: #{error.message}"
+    end
+
+    def write(config)
+      config_path.write(YAML.dump(config))
+    end
+
+    def profile_named(name, config = data)
+      profile = config.fetch("profiles")[name]
+      raise ProfileNotFound, "Unknown design profile: #{name}" unless profile.is_a?(Hash)
+
+      profile
+    end
+
+    def config_path
+      @root.join(CONFIG_PATH)
+    end
+
+    def references_path
+      @root.join("config/design_profiles/references")
+    end
+
+    def validate_slug!(slug)
+      return if slug.match?(/\A[a-z0-9]+(?:-[a-z0-9]+)*\z/)
+
+      raise ConfigurationError, "Invalid catalog slug: #{slug.inspect}"
+    end
+
+    def valid_token?(name, value)
+      name.is_a?(String) && value.is_a?(String) &&
+        name.match?(/\A[a-z0-9]+(?:-[a-z0-9]+)*\z/) &&
+        value.match?(/\A[a-zA-Z0-9#%.,()\s\/'\"+*_\-]+\z/)
+    end
+  end
+end
+

data/lib/rails_design_profiles/railtie.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module RailsDesignProfiles
+  class Railtie < Rails::Railtie
+    initializer "rails_design_profiles.helper" do
+      ActiveSupport.on_load(:action_view) { include RailsDesignProfiles::Helper }
+    end
+
+    rake_tasks do
+      load File.expand_path("../tasks/rails_design_profiles_tasks.rake", __dir__)
+    end
+  end
+end
+

data/lib/rails_design_profiles/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RailsDesignProfiles
+  VERSION = "0.1.1"
+end

data/lib/rails_design_profiles.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "rails_design_profiles/version"
+require "rails_design_profiles/profile_store"
+require "rails_design_profiles/catalog_client"
+require "rails_design_profiles/helper"
+require "rails_design_profiles/railtie" if defined?(Rails::Railtie)
+
+module RailsDesignProfiles
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class ProfileNotFound < Error; end
+  class CatalogError < Error; end
+
+  class << self
+    attr_writer :root
+
+    def root
+      return @root if @root
+      return Rails.root if defined?(Rails) && Rails.respond_to?(:root)
+
+      Pathname.pwd
+    end
+
+    def store
+      ProfileStore.new(root)
+    end
+  end
+end
+

data/lib/tasks/rails_design_profiles_tasks.rake

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+namespace :design do
+  desc "List public DESIGN.md references from VoltAgent/awesome-design-md"
+  task :list do
+    RailsDesignProfiles::CatalogClient.new.slugs.each { |slug| puts slug }
+  end
+
+  desc "Download a public DESIGN.md reference and create a blank token profile"
+  task :install, [:slug] => :environment do |_task, arguments|
+    slug = arguments.fetch(:slug) { abort "Usage: rails design:install[slug]" }
+    contents = RailsDesignProfiles::CatalogClient.new.download(slug)
+    RailsDesignProfiles.store.install_reference!(slug, contents)
+    puts "Installed #{slug}. Add tokens to config/design_profiles.yml before activating it."
+  rescue RailsDesignProfiles::Error => error
+    abort error.message
+  end
+
+  desc "Set the active design profile"
+  task :activate, [:profile] => :environment do |_task, arguments|
+    profile = arguments.fetch(:profile) { abort "Usage: rails design:activate[profile]" }
+    RailsDesignProfiles.store.activate!(profile)
+    puts "Active design profile: #{profile}"
+  rescue RailsDesignProfiles::Error => error
+    abort error.message
+  end
+end
+

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: rails-design-profiles
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Fernando Paladini
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionview
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+description: Keep DESIGN.md references alongside executable, reviewable CSS token
+  profiles in Rails.
+email:
+- fnpaladini@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- CONTRIBUTING.md
+- LICENSE.txt
+- README.md
+- lib/generators/rails_design_profiles/install/install_generator.rb
+- lib/generators/rails_design_profiles/install/templates/design_profiles.yml
+- lib/rails_design_profiles.rb
+- lib/rails_design_profiles/catalog_client.rb
+- lib/rails_design_profiles/helper.rb
+- lib/rails_design_profiles/profile_store.rb
+- lib/rails_design_profiles/railtie.rb
+- lib/rails_design_profiles/version.rb
+- lib/tasks/rails_design_profiles_tasks.rake
+homepage: https://github.com/paladini/rails-design-profiles
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/paladini/rails-design-profiles
+  changelog_uri: https://github.com/paladini/rails-design-profiles/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.16
+specification_version: 4
+summary: Versioned, CSS-variable design profiles for Rails applications.
+test_files: []