add docs for shards' capacity health indicator (#94738)

docs/reference/health/health.asciidoc

@@ -78,6 +78,10 @@ for health status set `verbose` to `false` to disable the more expensive analysi
   `slm`::
       Reports health issues related to
       Snapshot Lifecycle Management.
+
+  `shards_capacity`::
+      Reports health issues related to the shards
+      capacity of the cluster.
 --
 
 [[health-api-query-params]]
@@ -377,6 +381,36 @@ watermark threshold>>.
     The `invocations_since_last_success` key will report a map where the unhealthy policy
     name is the key and it's corresponding number of failed invocations is the value.
 
+[[health-api-response-details-shards-usage]]
+===== shards_capacity
+`data`::
+(map) A view with information about the current capacity of shards for data nodes that do not belong to the frozen tier.
++
+.Properties of `data`
+[%collapsible%open]
+=====
+`max_shards_in_cluster`::
+(int) Indicates the maximum number of shards that the cluster can hold.
+
+`current_used_shards`::
+(optional, int) The total number of shards hold by the cluster. Only displayed in the case the indicator's status is `red` or `yellow`.
+
+=====
+
+`frozen`::
+(map) A view with information about the current capacity of shards for data nodes that belong to the frozen tier.
++
+.Properties of `frozen`
+[%collapsible%open]
+=====
+`max_shards_in_cluster`::
+(int) Indicates the maximum number of shards the cluster can hold for the partially mounted indices.
+
+`current_used_shards`::
+(optional, int) The total number of shards the partially mounted indices have in the cluster. Only displayed in the case the indicator's status is `red` or `yellow`.
+
+=====
+
 [[health-api-example]]
 ==== {api-examples-title}