{
  "feature": "color-system",
  "version": "1.0.0",
  "category": "ui",
  "description": "Define a structured color palette using HSL for better shade control, ensuring sufficient colors for hierarchy while avoiding over-saturation and maintaining accessibility for color-blind users.\n",
  "rules": {
    "use_hsl_instead_of_hex": "Use HSL instead of hex — easier to understand (Hue 0-360°, Saturation 0-100%, Lightness 0-100%) and generate shades",
    "need_more_colors_than_you_think": "You need more colors than you think — plan for 5-8 base colors with 5-9 shades each (dark, lighter, lightest, etc.)",
    "define_shades_up_front": "Define shades up front — don't generate them ad-hoc; create a structured palette",
    "dont_let_lightness_kill_saturation": "Don't let lightness kill saturation — reduce saturation as lightness increases to keep colors vibrant",
    "greys_dont_have_to_be_grey": "Greys don't have to be grey — subtle hue can make neutrals feel warmer or cooler",
    "accessible_doesnt_have_to_be_ugly": "Accessible doesn't have to mean ugly — sufficient contrast is possible with saturated, modern colors",
    "dont_rely_on_color_alone": "Don't rely on color alone — always pair color with other signals (icon, text, weight) for color-blind users"
  },
  "outcomes": {
    "design_system_initiated": {
      "priority": 1,
      "given": [
        "design system is initiated"
      ],
      "then": [
        {
          "action": "create_record",
          "target": "color_palette",
          "type": "color_palette",
          "payload": [
            "base_colors",
            "shade_variants",
            "accent_colors"
          ]
        },
        {
          "action": "set_field",
          "target": "base_color_count",
          "value": "5-8"
        },
        {
          "action": "set_field",
          "target": "shades_per_color",
          "value": "5-9"
        }
      ],
      "result": "color palette is comprehensive and systematic"
    },
    "color_shade_generated": {
      "priority": 2,
      "given": [
        "color shade is generated"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "hue",
          "value": "constant"
        },
        {
          "action": "set_field",
          "target": "saturation",
          "value": "high for dark shades, reduced as lightness increases"
        },
        {
          "action": "set_field",
          "target": "lightness",
          "value": "varies to create contrast"
        }
      ],
      "result": "shade remains true to base hue and maintains vibrancy across the range"
    },
    "text_color_applied_to_background": {
      "priority": 3,
      "given": [
        "text color is applied to background"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "contrast_ratio",
          "value": ">=4.5:1 for normal text, >=3:1 for large text"
        },
        {
          "action": "set_field",
          "target": "tested_for",
          "value": "WCAG AA at minimum"
        }
      ],
      "result": "text is readable for users with low vision and color-blindness"
    },
    "information_conveyed_through_color": {
      "priority": 4,
      "given": [
        "information or meaning is conveyed through color"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "secondary_indicator",
          "value": "icon, text label, or pattern"
        },
        {
          "action": "emit_event",
          "event": "color.accessibility.checked",
          "payload": [
            "color_blind_simulation"
          ]
        }
      ],
      "result": "meaning is conveyed to color-blind users without color alone"
    },
    "neutral_background_color_selected": {
      "priority": 5,
      "given": [
        "neutral or background color is selected"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "hue",
          "value": "subtle warm or cool bias (not pure grey)"
        },
        {
          "action": "set_field",
          "target": "saturation",
          "value": "2-5%"
        }
      ],
      "result": "neutral feels intentional and cohesive with brand rather than colorless"
    }
  },
  "fields": [
    {
      "name": "primary_colors",
      "type": "text",
      "label": "Main brand and action colors (5-8 base hues)",
      "required": false
    },
    {
      "name": "neutral_palette",
      "type": "text",
      "label": "Greys and near-neutrals with subtle hue biases",
      "required": false
    },
    {
      "name": "accent_colors",
      "type": "text",
      "label": "Alert, error, success, warning colors with sufficient contrast",
      "required": false
    },
    {
      "name": "color_format",
      "type": "text",
      "label": "Preferred format: HSL (recommended) or hex",
      "required": false
    },
    {
      "name": "contrast_standard",
      "type": "text",
      "label": "Minimum contrast ratio (WCAG AA 4.5:1 or AAA 7:1)",
      "required": false
    }
  ],
  "tags": [
    "design-system",
    "accessibility",
    "visual-design"
  ],
  "related": [
    {
      "feature": "visual-hierarchy",
      "type": "required",
      "reason": "Color is a tool for expressing hierarchy and emphasis"
    },
    {
      "feature": "dark-mode",
      "type": "recommended",
      "reason": "Color system must work in both light and dark modes"
    },
    {
      "feature": "accessibility",
      "type": "required",
      "reason": "Color choices must pass contrast ratios and avoid color-only meaning"
    }
  ],
  "agi": {
    "goals": [
      {
        "id": "reliable_color_system",
        "description": "Define a structured color palette using HSL for better shade control, ensuring sufficient colors for hierarchy while avoiding over-saturation and maintaining accessibility for color-blind users.\n",
        "success_metrics": [
          {
            "metric": "success_rate",
            "target": ">= 99%",
            "measurement": "Successful operations divided by total attempts"
          },
          {
            "metric": "error_rate",
            "target": "< 1%",
            "measurement": "Failed operations divided by total attempts"
          }
        ],
        "constraints": []
      }
    ],
    "autonomy": {
      "level": "semi_autonomous"
    },
    "safety": {
      "action_permissions": [
        {
          "action": "design_system_initiated",
          "permission": "autonomous"
        },
        {
          "action": "color_shade_generated",
          "permission": "autonomous"
        },
        {
          "action": "text_color_applied_to_background",
          "permission": "autonomous"
        },
        {
          "action": "information_conveyed_through_color",
          "permission": "autonomous"
        },
        {
          "action": "neutral_background_color_selected",
          "permission": "autonomous"
        }
      ]
    },
    "tradeoffs": [
      {
        "prefer": "accessibility",
        "over": "aesthetics",
        "reason": "UI must be usable by all users including those with disabilities"
      }
    ],
    "coordination": {
      "protocol": "request_response",
      "consumes": [
        {
          "capability": "visual_hierarchy",
          "from": "visual-hierarchy",
          "fallback": "degrade"
        },
        {
          "capability": "accessibility",
          "from": "accessibility",
          "fallback": "degrade"
        }
      ]
    }
  }
}