{
  "feature": "depth-elevation",
  "version": "1.0.0",
  "category": "ui",
  "description": "Use shadows, layering, and spatial relationships to create visual depth and communicate elevation, even in flat designs, making clickable elements feel interactive and content hierarchy clear.\n",
  "rules": {
    "emulate_a_light_source": "Emulate a light source — consistent shadow direction (typically top-left light) creates believable depth",
    "use_shadows_to_convey_elevation": "Use shadows to convey elevation — stronger shadows = higher elevation; no shadow = background level",
    "shadows_can_have_two_parts": "Shadows can have two parts — a soft, larger shadow (ambient) and a sharper, smaller shadow (contact)",
    "even_flat_designs_can_have_depth": "Even flat designs can have depth — shadows on flat surfaces are effective without skeuomorphism",
    "overlap_elements_to_create_layers": "Overlap elements to create layers — slight overlap communicates spatial relationship and depth"
  },
  "outcomes": {
    "modal_floating_panel_displayed": {
      "priority": 1,
      "given": [
        "modal or floating panel is displayed above content"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "elevation_level",
          "value": "highest"
        },
        {
          "action": "set_field",
          "target": "shadow_blur",
          "value": "16-24px"
        },
        {
          "action": "set_field",
          "target": "shadow_spread",
          "value": "0 to 8px"
        },
        {
          "action": "set_field",
          "target": "shadow_opacity",
          "value": "15-25%"
        },
        {
          "action": "set_field",
          "target": "shadow_offset",
          "value": "0 12px (down and slightly forward)"
        }
      ],
      "result": "modal clearly appears above all other content and captures focus"
    },
    "card_raised_element_on_background": {
      "priority": 2,
      "given": [
        "card or raised element is on background"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "elevation_level",
          "value": "medium"
        },
        {
          "action": "set_field",
          "target": "shadow_blur",
          "value": "8-12px"
        },
        {
          "action": "set_field",
          "target": "shadow_spread",
          "value": "0 to 4px"
        },
        {
          "action": "set_field",
          "target": "shadow_opacity",
          "value": "10-15%"
        }
      ],
      "result": "card appears layered above background without excessive visual weight"
    },
    "button_interactive_element_at_rest": {
      "priority": 3,
      "given": [
        "button or interactive element is at rest"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "elevation_level",
          "value": "low or none"
        },
        {
          "action": "set_field",
          "target": "shadow",
          "value": "subtle or none at rest"
        },
        {
          "action": "transition_state",
          "field": "element_state",
          "from": "rest",
          "to": "hover"
        },
        {
          "action": "set_field",
          "target": "shadow",
          "value": "small shadow on hover"
        }
      ],
      "result": "button feels raised on interaction, subtle at rest"
    },
    "elements_layered_with_overlay": {
      "priority": 4,
      "given": [
        "elements are layered (e.g., image with overlay)"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "overlap_offset",
          "value": "8-16px"
        },
        {
          "action": "set_field",
          "target": "shadow_on_overlapping",
          "value": "optional subtle shadow"
        }
      ],
      "result": "layering is clear and suggests spatial depth"
    }
  },
  "fields": [
    {
      "name": "light_source_direction",
      "type": "text",
      "label": "Direction of primary light (e.g., top-left, directly above)",
      "required": false
    },
    {
      "name": "shadow_levels",
      "type": "text",
      "label": "Predefined shadow styles for different elevations (background, card, modal)",
      "required": false
    },
    {
      "name": "max_shadow_blur",
      "type": "number",
      "label": "Maximum blur radius for largest shadows (typically 24px)",
      "required": false
    },
    {
      "name": "interaction_shadow_change",
      "type": "text",
      "label": "How shadows change on hover/active (increase blur, offset, or opacity)",
      "required": false
    }
  ],
  "tags": [
    "design-system",
    "visual-design",
    "interaction-design"
  ],
  "related": [
    {
      "feature": "visual-hierarchy",
      "type": "recommended",
      "reason": "Elevation and shadows express hierarchy through spatial positioning"
    },
    {
      "feature": "color-system",
      "type": "recommended",
      "reason": "Shadow color is derived from brand darkness, not pure black"
    },
    {
      "feature": "dark-mode",
      "type": "recommended",
      "reason": "Shadow appearance differs in dark mode (lighter shadows on dark backgrounds)"
    },
    {
      "feature": "animation-state-machine",
      "type": "optional",
      "reason": "Shadows can animate smoothly during state transitions"
    }
  ],
  "agi": {
    "goals": [
      {
        "id": "reliable_depth_elevation",
        "description": "Use shadows, layering, and spatial relationships to create visual depth and communicate elevation, even in flat designs, making clickable elements feel interactive and content hierarchy clear.\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": "modal_floating_panel_displayed",
          "permission": "autonomous"
        },
        {
          "action": "card_raised_element_on_background",
          "permission": "autonomous"
        },
        {
          "action": "button_interactive_element_at_rest",
          "permission": "autonomous"
        },
        {
          "action": "elements_layered_with_overlay",
          "permission": "autonomous"
        }
      ]
    },
    "tradeoffs": [
      {
        "prefer": "accessibility",
        "over": "aesthetics",
        "reason": "UI must be usable by all users including those with disabilities"
      }
    ]
  }
}