{
  "feature": "visual-hierarchy",
  "version": "1.0.0",
  "category": "ui",
  "description": "Establish clear visual hierarchy through size, weight, color, and spacing so users can quickly scan and understand interface priority without cognitive overload.\n",
  "rules": {
    "not_all_elements_equal": "Not all elements should be equal — differentiate primary content from secondary",
    "use_size_strategically": "Use size strategically — scale is the most powerful hierarchy tool after careful spacing",
    "no_grey_on_colored_backgrounds": "Don't use grey text on colored backgrounds — reduces contrast and harm accessibility",
    "emphasize_by_deemphasizing": "Emphasize by de-emphasizing — make less important elements quieter, not primary ones louder",
    "never_use_labels_as_primary_identity": "Never use labels as primary identity — labels are a last resort after visual hierarchy fails",
    "separate_visual_from_document_hierarchy": "Separate visual hierarchy from document hierarchy — visual and structural order needn't match"
  },
  "outcomes": {
    "user_scans_interface": {
      "priority": 1,
      "given": [
        "user scans interface for key information"
      ],
      "then": [
        "primary actions and content are visually distinct through size, weight, or color",
        "secondary elements are de-emphasized through reduced opacity, weight, or color intensity",
        "all elements have clear visual relationships expressed in spacing and contrast"
      ],
      "result": "user can scan interface in under 2 seconds without reading labels"
    },
    "interface_has_multiple_sections": {
      "priority": 2,
      "given": [
        "interface has multiple content sections"
      ],
      "then": [
        "section headings use significantly larger type size than body content",
        "heading weight (font-weight) is proportional to hierarchy level",
        "spacing between hierarchy levels increases as importance decreases"
      ],
      "result": "visual structure is immediately apparent without visual stress"
    },
    "critical_element_needs_attention": {
      "priority": 3,
      "given": [
        "action or data point is critical to task completion"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "element_size",
          "value": "largest in context"
        },
        {
          "action": "set_field",
          "target": "color_saturation",
          "value": "highest in context"
        },
        {
          "action": "set_field",
          "target": "contrast_ratio",
          "value": ">=7:1"
        }
      ],
      "result": "critical element has no visual competitors for user attention"
    },
    "low_priority_content_present": {
      "priority": 4,
      "given": [
        "interface has low-priority metadata or supporting info"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "text_color",
          "value": "reduced_saturation or opacity < 100%"
        },
        {
          "action": "set_field",
          "target": "font_weight",
          "value": "lighter than body"
        },
        {
          "action": "set_field",
          "target": "element_size",
          "value": "12-14px for web"
        }
      ],
      "result": "low-priority content is accessible but won't distract from primary content"
    }
  },
  "fields": [
    {
      "name": "primary_content",
      "type": "text",
      "label": "Main content user came to interface to interact with",
      "required": false
    },
    {
      "name": "secondary_content",
      "type": "text",
      "label": "Supporting information or metadata",
      "required": false
    },
    {
      "name": "tertiary_content",
      "type": "text",
      "label": "Additional details, help text, or background info",
      "required": false
    },
    {
      "name": "hierarchy_levels",
      "type": "number",
      "label": "Number of distinct visual hierarchy tiers in this interface (typically 3-5)",
      "required": false
    }
  ],
  "tags": [
    "design-system",
    "accessibility",
    "visual-design"
  ],
  "related": [
    {
      "feature": "typography-system",
      "type": "recommended",
      "reason": "Type scales and font selection enforce hierarchy through size relationships"
    },
    {
      "feature": "spacing-system",
      "type": "recommended",
      "reason": "Spacing reinforces visual hierarchy through whitespace and grouping"
    },
    {
      "feature": "color-system",
      "type": "recommended",
      "reason": "Color, saturation, and contrast tools for visual differentiation"
    },
    {
      "feature": "accessibility",
      "type": "required",
      "reason": "Visual hierarchy must maintain sufficient contrast for WCAG AA compliance"
    }
  ],
  "agi": {
    "goals": [
      {
        "id": "reliable_visual_hierarchy",
        "description": "Establish clear visual hierarchy through size, weight, color, and spacing so users can quickly scan and understand interface priority without cognitive overload.\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": "user_scans_interface",
          "permission": "autonomous"
        },
        {
          "action": "interface_has_multiple_sections",
          "permission": "autonomous"
        },
        {
          "action": "critical_element_needs_attention",
          "permission": "autonomous"
        },
        {
          "action": "low_priority_content_present",
          "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": "accessibility",
          "from": "accessibility",
          "fallback": "degrade"
        }
      ]
    }
  }
}