unmagic-color 0.1.0 → 0.2.1

data/lib/unmagic/color/oklch.rb

@@ -77,24 +77,29 @@ module Unmagic
       # Error raised when parsing OKLCH color strings fails
       class ParseError < Color::Error; end
 
-      attr_reader :chroma, :hue
+      attr_reader :chroma, :hue, :alpha
 
       # Create a new OKLCH color.
       #
       # @param lightness [Float] Lightness as a ratio (0.0-1.0), clamped to range
       # @param chroma [Float] Chroma intensity (0.0-0.5), clamped to range
       # @param hue [Numeric] Hue in degrees (0-360), wraps around if outside range
+      # @param alpha [Numeric, Color::Alpha, nil] Alpha channel (0-100%), defaults to 100 (fully opaque)
       #
       # @example Create a medium blue
       #   OKLCH.new(lightness: 0.65, chroma: 0.15, hue: 240)
       #
+      # @example Create a semi-transparent red
+      #   OKLCH.new(lightness: 0.60, chroma: 0.25, hue: 30, alpha: 50)
+      #
       # @example Create a vibrant red
       #   OKLCH.new(lightness: 0.60, chroma: 0.25, hue: 30)
-      def initialize(lightness:, chroma:, hue:)
+      def initialize(lightness:, chroma:, hue:, alpha: nil)
         super()
-        @lightness = Color::Lightness.new(lightness * 100) # Convert 0-1 to percentage
+        @lightness = Color::Lightness.new(value: lightness * 100) # Convert 0-1 to percentage
         @chroma = Color::Chroma.new(value: chroma)
         @hue = Color::Hue.new(value: hue)
+        @alpha = Color::Alpha.build(alpha) || Color::Alpha::DEFAULT
       end
 
       # Get the lightness as a ratio (0.0-1.0).
@@ -116,9 +121,9 @@ module Unmagic
         # Parse an OKLCH color from a string.
         #
         # Accepts formats:
-        # - CSS format: "oklch(0.65 0.15 240)"
+        # - CSS format: "oklch(0.65 0.15 240)" or "oklch(0.65 0.15 240 / 0.5)"
         # - Raw values: "0.65 0.15 240"
-        # - Space-separated values
+        # - Space-separated values with optional alpha after slash
         #
         # @param input [String] The OKLCH color string to parse
         # @return [OKLCH] The parsed OKLCH color
@@ -127,6 +132,9 @@ module Unmagic
         # @example Parse CSS format
         #   OKLCH.parse("oklch(0.65 0.15 240)")
         #
+        # @example Parse with alpha
+        #   OKLCH.parse("oklch(0.65 0.15 240 / 0.5)")
+        #
         # @example Parse without function wrapper
         #   OKLCH.parse("0.58 0.12 180")
         def parse(input)
@@ -135,6 +143,16 @@ module Unmagic
           # Remove oklch() wrapper if present
           clean = input.gsub(/^oklch\s*\(\s*|\s*\)$/, "").strip
 
+          # Check for alpha with slash separator
+          alpha = nil
+          if clean.include?("/")
+            parts = clean.split("/").map(&:strip)
+            raise ParseError, "Invalid format with /: expected 'L C H / alpha'" unless parts.length == 2
+
+            clean = parts[0]
+            alpha = Color::Alpha.parse(parts[1])
+          end
+
           # Split values
           parts = clean.split(/\s+/)
           unless parts.length == 3
@@ -167,7 +185,36 @@ module Unmagic
             raise ParseError, "Hue must be between 0 and 360, got #{h}"
           end
 
-          new(lightness: l, chroma: c, hue: h)
+          new(lightness: l, chroma: c, hue: h, alpha: alpha)
+        end
+
+        # Build an OKLCH color from a string, positional values, or keyword arguments.
+        #
+        # @param args [String, Numeric] Either a color string or 3 component values
+        # @option kwargs [Numeric] :lightness Lightness (0-1)
+        # @option kwargs [Numeric] :chroma Chroma (0-0.5)
+        # @option kwargs [Numeric] :hue Hue in degrees (0-360)
+        # @return [OKLCH] The constructed OKLCH color
+        #
+        # @example From string
+        #   OKLCH.build("oklch(0.65 0.15 240)")
+        #
+        # @example From positional values
+        #   OKLCH.build(0.65, 0.15, 240)
+        #
+        # @example From keyword arguments
+        #   OKLCH.build(lightness: 0.65, chroma: 0.15, hue: 240)
+        def build(*args, **kwargs)
+          if kwargs.any?
+            new(**kwargs)
+          elsif args.length == 1
+            parse(args[0])
+          elsif args.length == 3
+            values = args.map { |v| v.is_a?(::String) ? v.to_f : v }
+            new(lightness: values[0], chroma: values[1], hue: values[2])
+          else
+            raise ArgumentError, "Expected 1 or 3 arguments, got #{args.length}"
+          end
         end
 
         # Generate a deterministic OKLCH color from an integer seed.
@@ -219,6 +266,15 @@ module Unmagic
         self
       end
 
+      # Convert to HSL color space.
+      #
+      # Converts via RGB as an intermediate step.
+      #
+      # @return [HSL] The color in HSL color space
+      def to_hsl
+        to_rgb.to_hsl
+      end
+
       # Convert to RGB color space.
       #
       # @return [RGB] The color in RGB color space (approximation)
@@ -243,7 +299,16 @@ module Unmagic
         g = (base + g_offset).clamp(0, 255)
         b = (base + b_offset).clamp(0, 255)
 
-        Unmagic::Color::RGB.new(red: r, green: g, blue: b)
+        Unmagic::Color::RGB.new(red: r, green: g, blue: b, alpha: @alpha)
+      end
+
+      # Convert to hex string.
+      #
+      # Converts via RGB as an intermediate step.
+      #
+      # @return [String] The color as a hex string (e.g., "#ff5733")
+      def to_hex
+        to_rgb.to_hex
       end
 
       # Calculate the relative luminance.
@@ -271,7 +336,7 @@ module Unmagic
       def lighten(amount = 0.03)
         current_lightness = @lightness.to_ratio
         new_lightness = clamp01(current_lightness + amount)
-        self.class.new(lightness: new_lightness, chroma: @chroma.value, hue: @hue.value)
+        self.class.new(lightness: new_lightness, chroma: @chroma.value, hue: @hue.value, alpha: @alpha.value)
       end
 
       # Create a darker version by decreasing lightness.
@@ -350,19 +415,33 @@ module Unmagic
         new_lightness = lightness + (other_oklch.lightness - lightness) * amount
         new_chroma = @chroma.value + (other_oklch.chroma.value - @chroma.value) * amount
 
-        self.class.new(lightness: new_lightness, chroma: new_chroma, hue: new_hue)
+        self.class.new(
+          lightness: new_lightness,
+          chroma: new_chroma,
+          hue: new_hue,
+          alpha: @alpha.value * (1 - amount) + other_oklch.alpha.value * amount,
+        )
       end
 
       # Convert to CSS oklch() function format.
       #
-      # @return [String] CSS string like "oklch(0.6500 0.1500 240.00)"
+      # @return [String] CSS string like "oklch(0.6500 0.1500 240.00)" or "oklch(0.6500 0.1500 240.00 / 0.5)"
       #
-      # @example
+      # @example Fully opaque
       #   color = OKLCH.new(lightness: 0.65, chroma: 0.15, hue: 240)
       #   color.to_css_oklch
       #   # => "oklch(0.6500 0.1500 240.00)"
+      #
+      # @example Semi-transparent
+      #   color = OKLCH.new(lightness: 0.65, chroma: 0.15, hue: 240, alpha: 50)
+      #   color.to_css_oklch
+      #   # => "oklch(0.6500 0.1500 240.00 / 0.5)"
       def to_css_oklch
-        format("oklch(%.4f %.4f %.2f)", @lightness.to_ratio, @chroma.value, @hue.value)
+        if @alpha.value < 100
+          format("oklch(%.4f %.4f %.2f / %s)", @lightness.to_ratio, @chroma.value, @hue.value, @alpha.to_css)
+        else
+          format("oklch(%.4f %.4f %.2f)", @lightness.to_ratio, @chroma.value, @hue.value)
+        end
       end
 
       # Convert to CSS custom properties (variables).
@@ -423,6 +502,39 @@ module Unmagic
         to_css_oklch
       end
 
+      # Convert to ANSI SGR color code.
+      #
+      # Converts to RGB first, then generates the ANSI code.
+      #
+      # @param layer [Symbol] Whether to generate foreground (:foreground) or background (:background) code
+      # @param mode [Symbol] Color format mode (:truecolor, :palette256, :palette16)
+      # @return [String] ANSI SGR code like "31" or "38;2;255;0;0"
+      #
+      # @example
+      #   color = OKLCH.new(lightness: 0.60, chroma: 0.25, hue: 30)
+      #   color.to_ansi
+      #   # => "38;2;..." (true color format)
+      def to_ansi(layer: :foreground, mode: :truecolor)
+        to_rgb.to_ansi(layer: layer, mode: mode)
+      end
+
+      # Pretty print support with colored swatch in class name.
+      #
+      # Outputs standard Ruby object format with a colored block character
+      # embedded in the class name area. Note: @lightness is shown via its
+      # inspect method since it's a Lightness percentage object.
+      #
+      # @param pp [PrettyPrint] The pretty printer instance
+      #
+      # @example
+      #   oklch = OKLCH.new(lightness: 0.65, chroma: 0.15, hue: 30)
+      #   pp oklch
+      #   # Outputs: #<Unmagic::Color::OKLCH[█] @lightness=... @chroma=0.15 @hue=30>
+      #   # (with colored █ block)
+      def pretty_print(pp)
+        pp.text("#<#{self.class.name}[\x1b[#{to_ansi(mode: :truecolor)}m█\x1b[0m] @lightness=#{@lightness.inspect} @chroma=#{@chroma.value.round(2)} @hue=#{@hue.value.round}>")
+      end
+
       private
 
       def clamp01(x)

data/lib/unmagic/color/rgb/ansi.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+module Unmagic
+  class Color
+    class RGB
+      # ANSI SGR (Select Graphic Rendition) color code parsing.
+      #
+      # Parses ANSI color codes used in terminal output. Handles standard 3/4-bit colors,
+      # 256-color palette, and 24-bit true color formats.
+      #
+      # ## Supported Formats
+      #
+      # Standard 3/4-bit colors (foreground and background):
+      #
+      #     Unmagic::Color::RGB::ANSI.parse("31")        # Red foreground
+      #     Unmagic::Color::RGB::ANSI.parse("41")        # Red background
+      #     Unmagic::Color::RGB::ANSI.parse("91")        # Bright red foreground
+      #     Unmagic::Color::RGB::ANSI.parse("101")       # Bright red background
+      #
+      # 256-color palette:
+      #
+      #     Unmagic::Color::RGB::ANSI.parse("38;5;196")  # Red foreground (256-color)
+      #     Unmagic::Color::RGB::ANSI.parse("48;5;196")  # Red background (256-color)
+      #
+      # 24-bit true color:
+      #
+      #     Unmagic::Color::RGB::ANSI.parse("38;2;255;0;0")    # Red foreground (true color)
+      #     Unmagic::Color::RGB::ANSI.parse("48;2;255;0;0")    # Red background (true color)
+      #
+      # @example Parse standard ANSI color
+      #   Unmagic::Color::RGB::ANSI.parse("31")
+      #   #=> RGB instance for red
+      #
+      # @example Parse 24-bit true color
+      #   Unmagic::Color::RGB::ANSI.parse("38;2;100;150;200")
+      #   #=> RGB instance for RGB(100, 150, 200)
+      class ANSI
+        # Error raised when parsing ANSI color codes fails
+        class ParseError < Color::Error; end
+
+        class << self
+          # Check if a string or integer is a valid ANSI color code.
+          #
+          # @param value [String, Integer] The value to validate
+          # @return [Boolean] true if valid ANSI code, false otherwise
+          #
+          # @example Check string
+          #   Unmagic::Color::RGB::ANSI.valid?("31")
+          #   #=> true
+          #
+          # @example Check integer
+          #   Unmagic::Color::RGB::ANSI.valid?(31)
+          #   #=> true
+          #
+          # @example Invalid input
+          #   Unmagic::Color::RGB::ANSI.valid?("invalid")
+          #   #=> false
+          def valid?(value)
+            parse(value)
+            true
+          rescue ParseError
+            false
+          end
+
+          # Parse an ANSI SGR color code.
+          #
+          # Accepts SGR parameters only (not full escape sequences).
+          # Handles foreground and background colors in all formats.
+          # Integers are automatically converted to strings.
+          #
+          # @param input [String, Integer] The ANSI code to parse
+          # @return [RGB] The parsed RGB color
+          # @raise [ParseError] If the input is not a valid ANSI color code
+          #
+          # @example Parse standard ANSI color with string
+          #   Unmagic::Color::RGB::ANSI.parse("31")
+          #   #=> Unmagic::Color::RGB instance for red
+          #
+          # @example Parse standard ANSI color with integer
+          #   Unmagic::Color::RGB::ANSI.parse(31)
+          #   #=> Unmagic::Color::RGB instance for red
+          #
+          # @example Parse 256-color palette
+          #   Unmagic::Color::RGB::ANSI.parse("38;5;196")
+          #   #=> Unmagic::Color::RGB instance for bright red
+          #
+          # @example Parse 24-bit true color
+          #   color = Unmagic::Color::RGB::ANSI.parse("38;2;100;150;200")
+          #   color.to_hex
+          #   #=> "#6496c8"
+          def parse(input)
+            raise ParseError, "Input must be a string or integer" unless input.is_a?(::String) || input.is_a?(::Integer)
+
+            # Convert integers to strings
+            input = input.to_s if input.is_a?(::Integer)
+
+            # Strip and validate format
+            clean = input.strip
+            raise ParseError, "Can't parse empty string" if clean.empty?
+
+            # Must be numeric with optional semicolons
+            unless clean.match?(/\A\d+(?:;\d+)*\z/)
+              raise ParseError, "Invalid ANSI format: #{input.inspect} (must be numeric with optional semicolons)"
+            end
+
+            # Split on semicolons
+            parts = clean.split(";").map(&:to_i)
+
+            parse_sgr_params(parts)
+          end
+
+          private
+
+          # Parse SGR parameters and return RGB color
+          def parse_sgr_params(parts)
+            first = parts[0]
+
+            # Check for extended color formats (38 or 48 prefix)
+            if first == 38 || first == 48
+              parse_extended_color(parts)
+            # Check for standard 3/4-bit colors
+            elsif standard_color?(first)
+              parse_standard_color(first)
+            else
+              raise ParseError, "Unknown ANSI color code: #{parts.join(";")}"
+            end
+          end
+
+          # Parse extended color formats (256-color or true color)
+          def parse_extended_color(parts)
+            raise ParseError, "Extended color format requires at least 3 parameters" if parts.length < 3
+
+            color_type = parts[1]
+
+            case color_type
+            when 5
+              # 256-color palette: 38;5;N or 48;5;N
+              parse_256_color(parts)
+            when 2
+              # 24-bit true color: 38;2;R;G;B or 48;2;R;G;B
+              parse_true_color(parts)
+            else
+              raise ParseError, "Unknown extended color type: #{color_type} (expected 2 for true color or 5 for 256-color)"
+            end
+          end
+
+          # Parse 256-color palette code
+          def parse_256_color(parts)
+            raise ParseError, "256-color format requires 3 parameters (e.g., 38;5;N)" unless parts.length == 3
+
+            color_256_to_rgb(parts[2])
+          end
+
+          # Parse 24-bit true color code
+          def parse_true_color(parts)
+            raise ParseError, "True color format requires 5 parameters (e.g., 38;2;R;G;B)" unless parts.length == 5
+
+            RGB.new(red: parts[2], green: parts[3], blue: parts[4])
+          end
+
+          # Check if code is a standard 3/4-bit color
+          def standard_color?(code)
+            # Foreground: 30-37 (normal), 90-97 (bright)
+            # Background: 40-47 (normal), 100-107 (bright)
+            (30..37).cover?(code) || (40..47).cover?(code) ||
+              (90..97).cover?(code) || (100..107).cover?(code)
+          end
+
+          # Parse standard 3/4-bit color code
+          def parse_standard_color(code)
+            # Extract color index (0-7)
+            index = if (30..37).cover?(code)
+              code - 30
+            elsif (40..47).cover?(code)
+              code - 40
+            elsif (90..97).cover?(code)
+              code - 90
+            elsif (100..107).cover?(code)
+              code - 100
+            end
+
+            standard_color_to_rgb(index)
+          end
+
+          # Convert standard color index to RGB
+          # Using bright ANSI colors for consistency
+          def standard_color_to_rgb(index)
+            case index
+            when 0 then RGB.new(red: 0, green: 0, blue: 0)         # black
+            when 1 then RGB.new(red: 255, green: 0, blue: 0)       # red
+            when 2 then RGB.new(red: 0, green: 255, blue: 0)       # green
+            when 3 then RGB.new(red: 255, green: 255, blue: 0)     # yellow
+            when 4 then RGB.new(red: 0, green: 0, blue: 255)       # blue
+            when 5 then RGB.new(red: 255, green: 0, blue: 255)     # magenta
+            when 6 then RGB.new(red: 0, green: 255, blue: 255)     # cyan
+            when 7 then RGB.new(red: 255, green: 255, blue: 255)   # white
+            else
+              raise ParseError, "Invalid color index: #{index}"
+            end
+          end
+
+          # Convert 256-color palette index to RGB
+          def color_256_to_rgb(index)
+            case index
+            when 0..15
+              # Standard colors (use same as 3/4-bit)
+              standard_color_to_rgb(index % 8)
+            when 16..231
+              # 6x6x6 RGB cube
+              index -= 16
+              r = (index / 36) * 51
+              g = ((index % 36) / 6) * 51
+              b = (index % 6) * 51
+              RGB.new(red: r, green: g, blue: b)
+            when 232..255
+              # Grayscale ramp
+              gray = 8 + (index - 232) * 10
+              RGB.new(red: gray, green: gray, blue: gray)
+            else
+              raise ParseError, "Invalid 256-color index: #{index}"
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/color/rgb/gradient/linear.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+module Unmagic
+  class Color
+    class RGB
+      # Gradient generation in RGB color space.
+      module Gradient
+        # Linear gradient interpolation in RGB color space.
+        #
+        # Creates smooth color transitions by interpolating RGB components linearly
+        # between color stops. Each color stop has a position (0.0-1.0) that defines
+        # where the color appears in the gradient.
+        #
+        # ## RGB Interpolation
+        #
+        # RGB gradients interpolate the red, green, and blue components separately.
+        # This can produce different visual results compared to HSL or OKLCH gradients,
+        # especially when transitioning through complementary colors.
+        #
+        # ## Examples
+        #
+        #   # Simple horizontal gradient
+        #   gradient = Unmagic::Color::RGB::Gradient::Linear.build(
+        #     ["#FF0000", "#0000FF"],
+        #     direction: "to right"
+        #   )
+        #   bitmap = gradient.rasterize(width: 10)
+        #   bitmap.pixels[0].map(&:to_hex)
+        #   #=> ["#ff0000", "#e60019", ..., "#0000ff"]
+        #
+        #   # Gradient with intermediate stops
+        #   gradient = Unmagic::Color::RGB::Gradient::Linear.build(
+        #     [
+        #       ["#FF0000", 0.0],   # Red at start
+        #       ["#00FF00", 0.5],   # Green at middle
+        #       ["#0000FF", 1.0]    # Blue at end
+        #     ],
+        #     direction: "to bottom"
+        #   )
+        #   bitmap = gradient.rasterize(width: 1, height: 20)
+        #
+        #   # Angled gradient
+        #   gradient = Unmagic::Color::RGB::Gradient::Linear.build(
+        #     ["#FF0000", "#0000FF"],
+        #     direction: "45deg"
+        #   )
+        #   bitmap = gradient.rasterize(width: 100, height: 100)
+        #
+        #   # Use Stop objects directly
+        #   stops = [
+        #     Unmagic::Color::Gradient::Stop.new(
+        #       color: Unmagic::Color::RGB.parse("#FF0000"),
+        #       position: 0.0
+        #     ),
+        #     Unmagic::Color::Gradient::Stop.new(
+        #       color: Unmagic::Color::RGB.parse("#0000FF"),
+        #       position: 1.0
+        #     )
+        #   ]
+        #   direction = Unmagic::Color::Units::Degrees::Direction::LEFT_TO_RIGHT
+        #   gradient = Unmagic::Color::RGB::Gradient::Linear.new(stops, direction: direction)
+        class Linear < Unmagic::Color::Gradient::Base
+          class << self
+            # Get the RGB color class.
+            #
+            # @return [Class] Unmagic::Color::RGB
+            def color_class
+              Unmagic::Color::RGB
+            end
+          end
+
+          # Rasterize the gradient to a bitmap.
+          #
+          # Generates a bitmap containing the gradient with support for angled directions.
+          # The direction is determined by the gradient's direction parameter.
+          #
+          # @param width [Integer] Width of the bitmap (default 1)
+          # @param height [Integer] Height of the bitmap (default 1)
+          # @return [Bitmap] A bitmap with the specified dimensions
+          #
+          # @raise [Error] If width or height is less than 1
+          def rasterize(width: 1, height: 1)
+            raise self.class::Error, "width must be at least 1" if width < 1
+            raise self.class::Error, "height must be at least 1" if height < 1
+
+            # Get the angle from the direction's "to" component
+            degrees = @direction.to.value
+
+            # Generate pixels row by row
+            pixels = Array.new(height) do |y|
+              Array.new(width) do |x|
+                position = calculate_position(x, y, width, height, degrees)
+                color_at_position(position)
+              end
+            end
+
+            Unmagic::Color::Gradient::Bitmap.new(
+              width: width,
+              height: height,
+              pixels: pixels,
+            )
+          end
+
+          private
+
+          def validate_color_types(stops)
+            stops.each_with_index do |stop, i|
+              unless stop.color.is_a?(Unmagic::Color::RGB)
+                raise self.class::Error, "stops[#{i}].color must be an RGB color"
+              end
+            end
+          end
+
+          # Calculate the position (0-1) of a pixel in the gradient.
+          #
+          # @param x [Integer] X coordinate
+          # @param y [Integer] Y coordinate
+          # @param width [Integer] Bitmap width
+          # @param height [Integer] Bitmap height
+          # @param degrees [Float] Gradient angle in degrees
+          # @return [Float] Position along gradient (0.0 to 1.0)
+          def calculate_position(x, y, width, height, degrees)
+            # Normalize coordinates to 0-1 range
+            nx = width > 1 ? x / (width - 1).to_f : 0.5
+            ny = height > 1 ? y / (height - 1).to_f : 0.5
+
+            # Calculate position based on angle
+            angle_rad = degrees * Math::PI / 180.0
+
+            # The gradient line goes in the direction of the angle
+            # 0° = to top (upward)
+            # 90° = to right
+            # 180° = to bottom (downward)
+            # 270° = to left
+            dx = Math.sin(angle_rad)
+            dy = Math.cos(angle_rad)
+
+            # Calculate position by projecting pixel onto gradient direction
+            # We want position 0 at the start and position 1 at the end
+            position = (nx - 0.5) * dx + (0.5 - ny) * dy + 0.5
+
+            # Clamp to valid range
+            position.clamp(0.0, 1.0)
+          end
+
+          # Get the color at a specific position in the gradient.
+          #
+          # @param position [Float] Position along gradient (0.0 to 1.0)
+          # @return [Color] The interpolated color at this position
+          def color_at_position(position)
+            start_stop, end_stop = find_bracket_stops(position)
+
+            if start_stop.position == end_stop.position
+              start_stop.color
+            else
+              segment_length = end_stop.position - start_stop.position
+              blend_amount = (position - start_stop.position) / segment_length
+              start_stop.color.blend(end_stop.color, blend_amount)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/unmagic/color/rgb/hex.rb

@@ -57,8 +57,9 @@ module Unmagic
 
           # Parse a hexadecimal color string.
           #
-          # Accepts both full (6-digit) and short (3-digit) hex formats,
-          # with or without the # prefix.
+          # Accepts full (6-digit) and short (3-digit) hex formats,
+          # with or without the # prefix. Also supports 8-digit (with alpha)
+          # and 4-digit short format with alpha.
           #
           # @param input [String] The hex color string to parse
           # @return [RGB] The parsed RGB color
@@ -69,15 +70,18 @@ module Unmagic
           #
           # @example Short format without hash
           #   Unmagic::Color::RGB::Hex.parse("F80")
+          #
+          # @example With alpha
+          #   Unmagic::Color::RGB::Hex.parse("#FF880080")
           def parse(input)
             raise ParseError, "Input must be a string" unless input.is_a?(::String)
 
             # Clean up the input
             hex = input.strip.gsub(/^#/, "")
 
-            # Check for valid length (3 or 6 characters)
-            unless hex.length == 3 || hex.length == 6
-              raise ParseError, "Invalid number of characters (got #{hex.length}, expected 3 or 6)"
+            # Check for valid length (3, 4, 6, or 8 characters)
+            unless [3, 4, 6, 8].include?(hex.length)
+              raise ParseError, "Invalid number of characters (got #{hex.length}, expected 3, 4, 6, or 8)"
             end
 
             # Check if all characters are valid hex digits
@@ -86,8 +90,8 @@ module Unmagic
               raise ParseError, "Invalid hex characters: #{invalid_chars.join(", ")}"
             end
 
-            # Handle 3-character hex codes
-            if hex.length == 3
+            # Handle 3 or 4-character hex codes (expand each digit)
+            if hex.length == 3 || hex.length == 4
               hex = hex.chars.map { |c| c * 2 }.join
             end
 
@@ -95,7 +99,15 @@ module Unmagic
             g = hex[2..3].to_i(16)
             b = hex[4..5].to_i(16)
 
-            RGB.new(red: r, green: g, blue: b)
+            # Parse alpha if present (8 characters total after expansion)
+            if hex.length == 8
+              a = hex[6..7].to_i(16)
+              # Convert 0-255 alpha to 0-100 percentage
+              alpha_percent = (a / 255.0 * 100).round(2)
+              RGB.build(red: r, green: g, blue: b, alpha: alpha_percent)
+            else
+              RGB.build(red: r, green: g, blue: b)
+            end
           end
         end
       end