{
  "feature": "utility-composition",
  "version": "1.0.0",
  "description": "Build user interfaces by composing utility classes with variants and modifiers to generate CSS rules",
  "category": "ui",
  "tags": [
    "utilities",
    "variants",
    "responsive",
    "state-modifiers"
  ],
  "actors": [
    {
      "id": "developer",
      "name": "Developer/Designer",
      "type": "human",
      "description": "Writes HTML/templates using utility classes"
    },
    {
      "id": "css_generator",
      "name": "CSS Generator",
      "type": "system",
      "description": "Parses utility class names and generates CSS rules"
    }
  ],
  "fields": [
    {
      "name": "utility_class_name",
      "type": "text",
      "required": true,
      "label": "Base utility class without variants (e.g., 'flex', 'p-4', 'text-blue-500')"
    },
    {
      "name": "variant_prefix",
      "type": "text",
      "required": false,
      "label": "Variant modifier before colon (e.g., 'hover', 'md', 'dark', 'group-hover')"
    },
    {
      "name": "modifier",
      "type": "text",
      "required": false,
      "label": "Optional modifier after slash to apply sub-values (e.g., opacity: 'p-4/50' means 50% opacity)"
    },
    {
      "name": "important_flag",
      "type": "boolean",
      "required": false,
      "label": "Whether to add !important to generated CSS rule (trailing ! in class name)"
    },
    {
      "name": "css_property",
      "type": "text",
      "required": true,
      "label": "CSS property applied by utility (e.g., 'display', 'padding', 'color')"
    },
    {
      "name": "css_value",
      "type": "text",
      "required": true,
      "label": "CSS value applied to property (e.g., 'flex', '1rem', '#3b82f6')"
    },
    {
      "name": "responsive_breakpoint",
      "type": "select",
      "required": false,
      "label": "Responsive breakpoint variant (sm, md, lg, xl, 2xl)",
      "options": [
        {
          "value": "sm",
          "label": "sm"
        },
        {
          "value": "md",
          "label": "md"
        },
        {
          "value": "lg",
          "label": "lg"
        },
        {
          "value": "xl",
          "label": "xl"
        },
        {
          "value": "2xl",
          "label": "2xl"
        }
      ]
    },
    {
      "name": "pseudo_class",
      "type": "select",
      "required": false,
      "label": "CSS pseudo-class variant",
      "options": [
        {
          "value": "hover",
          "label": "hover"
        },
        {
          "value": "focus",
          "label": "focus"
        },
        {
          "value": "active",
          "label": "active"
        },
        {
          "value": "group-hover",
          "label": "group-hover"
        },
        {
          "value": "first-child",
          "label": "first-child"
        },
        {
          "value": "last-child",
          "label": "last-child"
        },
        {
          "value": "odd",
          "label": "odd"
        },
        {
          "value": "even",
          "label": "even"
        },
        {
          "value": "visited",
          "label": "visited"
        },
        {
          "value": "target",
          "label": "target"
        }
      ]
    },
    {
      "name": "pseudo_element",
      "type": "select",
      "required": false,
      "label": "CSS pseudo-element variant",
      "options": [
        {
          "value": "before",
          "label": "before"
        },
        {
          "value": "after",
          "label": "after"
        },
        {
          "value": "placeholder",
          "label": "placeholder"
        },
        {
          "value": "selection",
          "label": "selection"
        },
        {
          "value": "marker",
          "label": "marker"
        },
        {
          "value": "first-line",
          "label": "first-line"
        },
        {
          "value": "first-letter",
          "label": "first-letter"
        },
        {
          "value": "backdrop",
          "label": "backdrop"
        }
      ]
    }
  ],
  "states": {
    "field": "class_status",
    "values": [
      {
        "value": "unrecognized",
        "description": "Utility class name does not match any known utility"
      },
      {
        "value": "parsed",
        "description": "Class name parsed successfully, variants and modifiers extracted",
        "initial": true
      },
      {
        "value": "compiled",
        "description": "CSS rules generated from utility and variants"
      },
      {
        "value": "sorted",
        "description": "CSS rules sorted by variant order and property order"
      }
    ]
  },
  "rules": {
    "parsing": [
      "Utility class format: [variant(s):]*utility[/modifier][!]",
      "Multiple variants chain with colons: 'md:hover:flex' (responsive + pseudo-class + utility)",
      "Unknown utilities are silently dropped, not compiled to CSS"
    ],
    "variants": [
      "Responsive variants (sm:, md:, lg:) generate CSS media queries based on breakpoints",
      "Pseudo-class variants (hover:, focus:) generate CSS :pseudo-class selectors",
      "Pseudo-element variants (before:, after:) generate CSS ::pseudo-element selectors",
      "Dark mode variant (dark:) generates selector based on darkMode strategy (media, class, selector)",
      "Variant order matters: variants sort in a specific order for CSS cascade correctness"
    ],
    "composition": [
      "Single utility can have multiple variants; all variants apply to the same CSS rule",
      "Modifier (after /) applies additional behavior like opacity or color opacity",
      "Important flag (!) adds !important to generated CSS declaration"
    ],
    "performance": [
      "Duplicate class names are deduplicated; same utility+variants only generates CSS once"
    ]
  },
  "outcomes": {
    "simple_utility": {
      "priority": 1,
      "given": [
        "Developer writes utility class 'flex' in HTML",
        "flex utility is defined in design system"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "css_property",
          "value": "display"
        },
        {
          "action": "set_field",
          "target": "css_value",
          "value": "flex"
        },
        {
          "action": "emit_event",
          "event": "utility.compiled",
          "payload": [
            "utility_name",
            "css_property",
            "css_value"
          ]
        }
      ],
      "result": "CSS rule generated: .flex { display: flex; }"
    },
    "utility_with_value": {
      "priority": 2,
      "given": [
        "Developer writes 'p-4' (padding with value from theme)",
        "spacing theme has value for 4 (e.g., 1rem)"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "css_property",
          "value": "padding"
        },
        {
          "action": "set_field",
          "target": "css_value",
          "value": "1rem"
        }
      ],
      "result": "CSS rule generated: .p-4 { padding: 1rem; }"
    },
    "responsive_utility": {
      "priority": 3,
      "given": [
        "Developer writes 'md:flex'",
        "md breakpoint is configured (e.g., 768px)"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "responsive_breakpoint",
          "value": "md"
        },
        {
          "action": "set_field",
          "target": "css_property",
          "value": "display"
        },
        {
          "action": "set_field",
          "target": "css_value",
          "value": "flex"
        }
      ],
      "result": "CSS rule in media query: @media (min-width: 768px) { .md\\:flex { display: flex; } }"
    },
    "hover_state_styling": {
      "priority": 4,
      "given": [
        "Developer writes 'hover:text-blue-500'",
        "text-blue-500 utility exists"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "pseudo_class",
          "value": "hover"
        },
        {
          "action": "set_field",
          "target": "css_property",
          "value": "color"
        },
        {
          "action": "set_field",
          "target": "css_value",
          "value": "#3b82f6"
        }
      ],
      "result": "CSS rule generated: .hover\\:text-blue-500:hover { color: #3b82f6; }"
    },
    "multiple_variants": {
      "priority": 5,
      "given": [
        "Developer writes 'md:hover:flex'",
        "md breakpoint and hover variant both exist"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "responsive_breakpoint",
          "value": "md"
        },
        {
          "action": "set_field",
          "target": "pseudo_class",
          "value": "hover"
        }
      ],
      "result": "CSS rule combines both: @media (min-width: 768px) { .md\\:hover\\:flex:hover { display: flex; } }"
    },
    "important_modifier": {
      "priority": 6,
      "given": [
        "Developer writes 'flex!' to force !important"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "important_flag",
          "value": true
        }
      ],
      "result": "CSS rule includes !important: .flex\\! { display: flex !important; }"
    },
    "modifier_opacity": {
      "priority": 7,
      "given": [
        "Developer writes 'p-4/50' (padding with 50% opacity)"
      ],
      "then": [
        {
          "action": "set_field",
          "target": "modifier",
          "value": "50"
        }
      ],
      "result": "CSS includes opacity modifier: .p-4\\/50 { padding: 1rem; opacity: 0.5; }"
    },
    "unknown_utility": {
      "priority": 10,
      "error": "UNKNOWN_UTILITY",
      "given": [
        "Developer writes 'unknown-class'",
        "unknown-class does not match any known utility"
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "utility.invalid",
          "payload": [
            "utility_name"
          ]
        }
      ],
      "result": "Class is skipped; no CSS generated for this utility"
    }
  },
  "errors": [
    {
      "code": "UNKNOWN_UTILITY",
      "status": 400,
      "message": "Utility class not recognized. Check the utility name spelling and ensure it's defined in your theme."
    },
    {
      "code": "INVALID_VARIANT_COMBINATION",
      "status": 400,
      "message": "This variant combination is not supported or not applicable to this utility."
    },
    {
      "code": "INVALID_MODIFIER",
      "status": 400,
      "message": "Modifier value is invalid for this utility (e.g., opacity must be 0-100)."
    }
  ],
  "events": [
    {
      "name": "utility.compiled",
      "payload": [
        "utility_name",
        "css_property",
        "css_value",
        "variants"
      ]
    },
    {
      "name": "utility.invalid",
      "payload": [
        "utility_name"
      ]
    }
  ],
  "related": [
    {
      "feature": "theme-configuration",
      "type": "required",
      "reason": "Utilities read values from theme configuration"
    },
    {
      "feature": "responsive-layout",
      "type": "recommended",
      "reason": "Responsive variants (md:, lg:) enable layout breakpoints"
    },
    {
      "feature": "arbitrary-values",
      "type": "optional",
      "reason": "Arbitrary values provide escape hatch for custom values"
    }
  ],
  "agi": {
    "goals": [
      {
        "id": "reliable_utility_composition",
        "description": "Build user interfaces by composing utility classes with variants and modifiers to generate CSS rules",
        "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",
      "human_checkpoints": [
        "before transitioning to a terminal state"
      ],
      "escalation_triggers": [
        "error_rate > 5"
      ]
    },
    "safety": {
      "action_permissions": [
        {
          "action": "simple_utility",
          "permission": "autonomous"
        },
        {
          "action": "utility_with_value",
          "permission": "autonomous"
        },
        {
          "action": "responsive_utility",
          "permission": "autonomous"
        },
        {
          "action": "hover_state_styling",
          "permission": "autonomous"
        },
        {
          "action": "multiple_variants",
          "permission": "autonomous"
        },
        {
          "action": "important_modifier",
          "permission": "supervised"
        },
        {
          "action": "modifier_opacity",
          "permission": "supervised"
        },
        {
          "action": "unknown_utility",
          "permission": "autonomous"
        }
      ]
    },
    "tradeoffs": [
      {
        "prefer": "accessibility",
        "over": "aesthetics",
        "reason": "UI must be usable by all users including those with disabilities"
      }
    ],
    "coordination": {
      "protocol": "orchestrated",
      "consumes": [
        {
          "capability": "theme_configuration",
          "from": "theme-configuration",
          "fallback": "degrade"
        }
      ]
    }
  },
  "extensions": {
    "tech_stack": {
      "language": "TypeScript + CSS",
      "parser": "Rust (crates/oxide for candidate parsing)"
    },
    "source_location": "packages/tailwindcss/src",
    "performance_notes": "Candidate parsing cached; invalid candidates tracked to prevent re-parsing"
  }
}