@etus/ui 0.1.0

package/src/components/primitives/ProgressCircle/README.md

@@ -0,0 +1,763 @@
+# ProgressCircle
+
+## Visão Geral
+
+O **ProgressCircle** é um componente de indicador de progresso circular do Design System ETUS, usado para exibir métricas e estados de conclusão em formato de anel. Construído com SVG nativo para renderização suave e acessibilidade completa.
+
+### Casos de Uso
+
+- Dashboard de métricas e KPIs
+- Indicadores de completude de perfil
+- Pontuações e avaliações circulares
+- Metas e objetivos com progresso visual
+- Loading states com progresso conhecido
+- Indicadores de capacidade (storage, quota)
+
+### Classificação
+
+**Categoria:** Atom (Primitivo)
+**Dependências:** Nenhuma externa (SVG nativo)
+
+---
+
+## Design Specs
+
+### Anatomia
+
+```
+        ╭────────────╮
+       ╱              ╲
+      │    ┌─────┐    │    <- Track (trilha cinza)
+      │    │ 75% │    │    <- Value (porcentagem)
+      │    │Users│    │    <- Label (opcional)
+      │    └─────┘    │
+       ╲              ╱
+        ╰──██████████╯     <- Indicator (preenchimento verde)
+
+Half-circle:
+        ╭──────██████╮
+       ╱              ╲
+      │    ┌─────┐
+      │    │ 75% │
+      │    │Users│
+```
+
+### Tamanhos (`size`)
+
+| Tamanho | Diâmetro | Stroke Width | Fonte Value | Fonte Label | Uso                  |
+| ------- | -------- | ------------ | ----------- | ----------- | -------------------- |
+| `xxs`   | 64px     | 4px          | text-sm     | text-xs     | Badges, ícones       |
+| `xs`    | 160px    | 8px          | text-2xl    | text-sm     | Cards compactos      |
+| `sm`    | 200px    | 10px         | text-3xl    | text-sm     | Cards médios         |
+| `md`    | 240px    | 12px         | text-4xl    | text-base   | Dashboards (default) |
+| `lg`    | 280px    | 14px         | text-5xl    | text-base   | Hero metrics         |
+
+### Formas (`shape`)
+
+| Forma         | Descrição               | Uso                        |
+| ------------- | ----------------------- | -------------------------- |
+| `circle`      | Círculo completo (360°) | Métricas gerais, progresso |
+| `half-circle` | Semicírculo (180°)      | Gauges, velocímetros       |
+
+### Cores (`color`)
+
+| Variante  | Track                   | Indicator            | Uso                      |
+| --------- | ----------------------- | -------------------- | ------------------------ |
+| `default` | `stroke-muted`          | `stroke-success`     | Progresso padrão (verde) |
+| `primary` | `stroke-primary/20`     | `stroke-primary`     | Ações principais         |
+| `success` | `stroke-success/20`     | `stroke-success`     | Sucesso, completo        |
+| `warning` | `stroke-warning/20`     | `stroke-warning`     | Alertas, atenção         |
+| `error`   | `stroke-destructive/20` | `stroke-destructive` | Erros, crítico           |
+
+### Estados
+
+| Estado | Comportamento | Visual                        |
+| ------ | ------------- | ----------------------------- |
+| 0%     | Início        | Apenas track visível          |
+| 1-99%  | Em progresso  | Indicator proporcional        |
+| 100%   | Completo      | Indicator preenche todo track |
+
+### Tokens Utilizados
+
+```css
+/* Tamanhos (por size) */
+--progress-circle-size-xxs-diameter     /* 64px */
+--progress-circle-size-xxs-stroke-width /* 4px */
+--progress-circle-size-xs-diameter      /* 160px */
+--progress-circle-size-xs-stroke-width  /* 8px */
+--progress-circle-size-sm-diameter      /* 200px */
+--progress-circle-size-sm-stroke-width  /* 10px */
+--progress-circle-size-md-diameter      /* 240px */
+--progress-circle-size-md-stroke-width  /* 12px */
+--progress-circle-size-lg-diameter      /* 280px */
+--progress-circle-size-lg-stroke-width  /* 14px */
+
+/* Cores Track */
+--progress-circle-track-color-default   /* muted */
+--progress-circle-track-color-primary   /* primary/20 */
+--progress-circle-track-color-success   /* success/20 */
+--progress-circle-track-color-warning   /* warning/20 */
+--progress-circle-track-color-error     /* destructive/20 */
+
+/* Cores Indicator */
+--progress-circle-indicator-color-default   /* success */
+--progress-circle-indicator-color-primary   /* primary */
+--progress-circle-indicator-color-success   /* success */
+--progress-circle-indicator-color-warning   /* warning */
+--progress-circle-indicator-color-error     /* destructive */
+
+/* Value (numero central) */
+--progress-circle-value-font-weight    /* semibold */
+--progress-circle-value-color          /* foreground */
+
+/* Label (texto abaixo) */
+--progress-circle-label-color          /* muted-foreground */
+
+/* Transicao */
+--progress-circle-indicator-transition /* all 300ms ease-out */
+
+/* Tipografia */
+tabular-nums           /* Alinhamento numerico */
+
+/* Reduced Motion */
+motion-reduce:transition-none
+```
+
+### data-slot
+
+```html
+<div data-slot="progress-circle">
+  <!-- Container -->
+  <svg data-slot="progress-circle-svg">
+    <circle data-slot="progress-circle-track">...</circle>
+    <circle data-slot="progress-circle-indicator">...</circle>
+  </svg>
+  <div data-slot="progress-circle-content">
+    <!-- Center content -->
+    <span data-slot="progress-circle-value">75%</span>
+    <span data-slot="progress-circle-label">Users</span>
+  </div>
+</div>
+```
+
+---
+
+## API
+
+### Props
+
+| Prop              | Tipo                                                          | Padrão             | Descrição                                                 |
+| ----------------- | ------------------------------------------------------------- | ------------------ | --------------------------------------------------------- |
+| `value`           | `number`                                                      | `0`                | Valor do progresso (0-100), ignorado quando indeterminate |
+| `indeterminate`   | `boolean`                                                     | `false`            | Ativa estado de loading contínuo com animação             |
+| `size`            | `"xxs" \| "xs" \| "sm" \| "md" \| "lg"`                       | `"md"`             | Variante de tamanho                                       |
+| `shape`           | `"circle" \| "half-circle"`                                   | `"circle"`         | Forma do indicador                                        |
+| `color`           | `"default" \| "primary" \| "success" \| "warning" \| "error"` | `"default"`        | Variante de cor                                           |
+| `label`           | `string`                                                      | -                  | Texto descritivo abaixo do valor                          |
+| `formatValue`     | `(value: number) => string`                                   | `(v) => \`${v}%\`` | Função para formatar o valor                              |
+| `showValue`       | `boolean`                                                     | `true`             | Se deve mostrar o valor no centro                         |
+| `strokeWidth`     | `number`                                                      | (auto por size)    | Espessura do stroke customizada                           |
+| `className`       | `string`                                                      | -                  | Classes CSS adicionais                                    |
+| `aria-label`      | `string`                                                      | -                  | Label acessível                                           |
+| `aria-labelledby` | `string`                                                      | -                  | ID do elemento que rotula                                 |
+
+### TypeScript
+
+```typescript
+import { cva, type VariantProps } from "class-variance-authority";
+
+// Types exportados
+type ProgressCircleSize = "xxs" | "xs" | "sm" | "md" | "lg";
+type ProgressCircleShape = "circle" | "half-circle";
+type ProgressCircleColor =
+  | "default"
+  | "primary"
+  | "success"
+  | "warning"
+  | "error";
+
+interface ProgressCircleProps {
+  value?: number;
+  indeterminate?: boolean;
+  size?: ProgressCircleSize;
+  shape?: ProgressCircleShape;
+  color?: ProgressCircleColor;
+  label?: string;
+  formatValue?: (value: number) => string;
+  showValue?: boolean;
+  strokeWidth?: number;
+  className?: string;
+  "aria-label"?: string;
+  "aria-labelledby"?: string;
+}
+```
+
+### Comparativo com Design Systems de Referência
+
+#### Matriz de Features (14 Design Systems)
+
+| Feature                | ETUS | Chakra | MUI | Mantine | AntD | NextUI | Spectrum | Fluent | Carbon | Blueprint | Prime |
+| ---------------------- | :--: | :----: | :-: | :-----: | :--: | :----: | :------: | :----: | :----: | :-------: | :---: |
+| **Circular**           |  ✓   |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |    ✓     |   ~    |   -    |     -     |   ✓   |
+| **Half-circle**        |  ✓   |   -    |  -  |    -    |  ✓   |   -    |    -     |   -    |   -    |     -     |   -   |
+| **Size variants**      |  ✓   |   ✓    |  -  |    ✓    |  ✓   |   ✓    |    ✓     |   ✓    |   -    |     -     |   ✓   |
+| **Color variants**     |  ✓   |   ✓    |  ✓  |    ✓    |  ✓   |   ✓    |    -     |   -    |   -    |     ✓     |   ✓   |
+| **Label inside**       |  ✓   |   ✓    |  -  |    ✓    |  ✓   |   ✓    |    ✓     |   -    |   -    |     -     |   ✓   |
+| **Custom strokeWidth** |  ✓   |   ✓    |  ✓  |    ✓    |  ~   |   ✓    |    -     |   -    |   -    |     -     |   -   |
+| **formatValue**        |  ✓   |   -    |  -  |    -    |  ✓   |   ✓    |    ✓     |   -    |   -    |     -     |   -   |
+| **Multi-section**      |  -   |   -    |  -  |    ✓    |  -   |   -    |    -     |   -    |   -    |     -     |   -   |
+| **Indeterminate**      |  -   |   ✓    |  ✓  |    -    |  -   |   ✓    |    ✓     |   ✓    |   -    |     -     |   -   |
+| **Gradient**           |  -   |   -    |  -  |    -    |  ✓   |   -    |    -     |   -    |   -    |     -     |   -   |
+| **data-slot**          |  ✓   |   -    |  -  |    -    |  -   |   ✓    |    -     |   -    |   -    |     -     |   -   |
+| **ARIA nativo**        |  ✓   |   ✓    |  ✓  |    ✓    |  ~   |   ✓    |    ✓     |   ✓    |   ✓    |     ✓     |   ✓   |
+
+**Legenda:** ✓ = Suporte completo | ~ = Parcial | - = Não suportado
+
+#### Comparativo de Props por Design System
+
+| Prop                    |    ETUS     |    Chakra    |     MUI     |   Mantine   |        AntD        |      NextUI      |
+| ----------------------- | :---------: | :----------: | :---------: | :---------: | :----------------: | :--------------: |
+| `value`                 |      ✓      |      ✓       |      ✓      | `sections`  |     `percent`      |        ✓         |
+| `size`                  |      ✓      |      ✓       |   `size`    |      ✓      |      `width`       |        ✓         |
+| `thickness/strokeWidth` |      ✓      | `thickness`  | `thickness` | `thickness` |   `strokeWidth`    |  `strokeWidth`   |
+| `color`                 |      ✓      |   `color`    |   `color`   |      -      |   `strokeColor`    |     `color`      |
+| `label`                 |      ✓      |   children   |      -      |   `label`   |      children      |     `label`      |
+| `formatValue`           |      ✓      |      -       |      -      |      -      |      `format`      | `formatOptions`  |
+| `shape`                 |      ✓      |      -       |      -      |      -      | `type="dashboard"` |        -         |
+| `showValue`             |      ✓      |      -       |      -      |      -      |     `showInfo`     | `showValueLabel` |
+| `capIsRound`            | ✓ (default) | `capIsRound` |      -      | `roundCaps` |  `strokeLinecap`   |        -         |
+
+#### Análise por Design System
+
+**Chakra UI (CircularProgress/ProgressCircle v3):**
+
+- Compound components (Root, Circle, Track, Range, ValueText)
+- `colorPalette` para esquema de cores
+- `capIsRound` para bordas arredondadas
+- Suporte a indeterminate state
+
+**MUI (CircularProgress):**
+
+- Foco em loading indicators
+- `variant="determinate"` ou `"indeterminate"`
+- `disableShrink` para performance
+- Não tem label built-in
+
+**Mantine (RingProgress):**
+
+- Multi-section com cores diferentes
+- `sections` array com value e color
+- `transitionDuration` para animações
+- Tooltip por seção
+
+**Ant Design (Progress type="circle"):**
+
+- `type="circle"` ou `"dashboard"` (half-circle)
+- `gapDegree` e `gapPosition` para gaps
+- `format` function para texto customizado
+- Suporte a gradient via `strokeColor`
+
+**NextUI/HeroUI (CircularProgress):**
+
+- Baseado em React Aria (excelente a11y)
+- `formatOptions` (Intl.NumberFormat)
+- Slots para customização (track, indicator, value)
+- Tailwind variants
+
+---
+
+## Acessibilidade (A11y)
+
+### ARIA Attributes
+
+| Atributo          | Valor           | Descrição                          |
+| ----------------- | --------------- | ---------------------------------- |
+| `role`            | `"progressbar"` | Identifica como barra de progresso |
+| `aria-valuenow`   | `number`        | Valor atual (0-100)                |
+| `aria-valuemin`   | `0`             | Valor mínimo                       |
+| `aria-valuemax`   | `100`           | Valor máximo                       |
+| `aria-label`      | `string`        | Label quando não há texto visível  |
+| `aria-labelledby` | `string`        | ID do elemento que rotula          |
+
+### Screen Readers
+
+```tsx
+// Anuncia: "75% progress"
+<ProgressCircle value={75} aria-label="Profile completion" />
+
+// Anuncia com label customizado
+<ProgressCircle
+  value={60}
+  label="Active users"
+  aria-label="60% of users are active"
+/>
+```
+
+### Conformidade WCAG
+
+| Critério                     | Status | Notas                              |
+| ---------------------------- | ------ | ---------------------------------- |
+| 1.3.1 Info and Relationships | ✓      | `role="progressbar"` semântico     |
+| 4.1.2 Name, Role, Value      | ✓      | ARIA values implementados          |
+| 1.4.1 Use of Color           | ~      | Label provê contexto adicional     |
+| 1.4.11 Non-text Contrast     | ✓      | Contraste adequado track/indicator |
+
+### Reduced Motion
+
+```css
+/* Transições desabilitadas para usuários que preferem */
+motion-reduce: transition-none;
+```
+
+### Comparativo A11y (Design Systems)
+
+| Feature                | ETUS | Chakra | MUI | Mantine | AntD | NextUI | React Aria |
+| ---------------------- | :--: | :----: | :-: | :-----: | :--: | :----: | :--------: |
+| **role="progressbar"** |  ✓   |   ✓    |  ✓  |    ✓    |  ~   |   ✓    |     ✓      |
+| **aria-valuenow**      |  ✓   |   ✓    |  ✓  |    ✓    |  ~   |   ✓    |     ✓      |
+| **aria-valuemin/max**  |  ✓   |   ✓    |  ✓  |    ✓    |  ~   |   ✓    |     ✓      |
+| **aria-label**         |  ✓   |   ✓    |  ✓  |    ✓    |  ~   |   ✓    |     ✓      |
+| **aria-labelledby**    |  ✓   |   ✓    |  ✓  |    -    |  -   |   ✓    |     ✓      |
+| **Reduced motion**     |  ✓   |   ✓    |  -  |    -    |  -   |   ✓    |     ✓      |
+
+---
+
+## Exemplos
+
+### Uso Básico
+
+```tsx
+import { ProgressCircle } from "@etus/ui";
+
+function Example() {
+  return <ProgressCircle value={75} />;
+}
+```
+
+### Com Label
+
+```tsx
+<ProgressCircle value={60} label="Active users" />
+<ProgressCircle value={85} label="Storage used" />
+<ProgressCircle value={42} label="Tasks complete" />
+```
+
+### Tamanhos
+
+```tsx
+<ProgressCircle value={75} size="xxs" />  {/* 64px - badges */}
+<ProgressCircle value={75} size="xs" />   {/* 160px - cards */}
+<ProgressCircle value={75} size="sm" />   {/* 200px */}
+<ProgressCircle value={75} size="md" />   {/* 240px - default */}
+<ProgressCircle value={75} size="lg" />   {/* 280px - hero */}
+```
+
+### Cores
+
+```tsx
+<ProgressCircle value={75} color="default" />   {/* Verde (success) */}
+<ProgressCircle value={75} color="primary" />   {/* Azul */}
+<ProgressCircle value={75} color="success" />   {/* Verde */}
+<ProgressCircle value={50} color="warning" />   {/* Amarelo */}
+<ProgressCircle value={25} color="error" />     {/* Vermelho */}
+```
+
+### Half-Circle (Gauge)
+
+```tsx
+<ProgressCircle value={80} shape="half-circle" />
+<ProgressCircle value={65} shape="half-circle" label="Speed" />
+```
+
+### Formato Customizado
+
+```tsx
+// Mostra "75 de 100"
+<ProgressCircle
+  value={75}
+  formatValue={(v) => `${v} de 100`}
+/>
+
+// Mostra "3/4"
+<ProgressCircle
+  value={75}
+  formatValue={() => "3/4"}
+/>
+
+// Mostra apenas valor sem %
+<ProgressCircle
+  value={85}
+  formatValue={(v) => String(v)}
+  label="Score"
+/>
+```
+
+### Sem Valor (Só Ring)
+
+```tsx
+<ProgressCircle value={75} showValue={false} />
+```
+
+### Stroke Width Customizado
+
+```tsx
+{
+  /* Fino */
+}
+<ProgressCircle value={75} strokeWidth={4} />;
+
+{
+  /* Grosso */
+}
+<ProgressCircle value={75} strokeWidth={20} />;
+```
+
+### Indeterminate State (Loading)
+
+```tsx
+// Via prop indeterminate
+<ProgressCircle indeterminate />
+
+// Com label
+<ProgressCircle indeterminate label="Loading..." />
+
+// Diferentes tamanhos
+<ProgressCircle indeterminate size="xs" />
+<ProgressCircle indeterminate size="md" />
+<ProgressCircle indeterminate size="lg" />
+
+// Com cores
+<ProgressCircle indeterminate color="primary" />
+<ProgressCircle indeterminate color="success" />
+```
+
+### Dashboard de Métricas
+
+```tsx
+function MetricsDashboard() {
+  return (
+    <div className="grid grid-cols-3 gap-8">
+      <ProgressCircle value={92} label="Uptime" color="success" size="sm" />
+      <ProgressCircle value={67} label="CPU Usage" color="warning" size="sm" />
+      <ProgressCircle value={45} label="Memory" color="primary" size="sm" />
+    </div>
+  );
+}
+```
+
+### Com Estado Controlado
+
+```tsx
+function ControlledProgress() {
+  const [progress, setProgress] = useState(0);
+
+  useEffect(() => {
+    const timer = setInterval(() => {
+      setProgress((prev) => (prev >= 100 ? 0 : prev + 1));
+    }, 100);
+    return () => clearInterval(timer);
+  }, []);
+
+  return <ProgressCircle value={progress} label="Loading..." />;
+}
+```
+
+### Card de Perfil
+
+```tsx
+function ProfileCompletion() {
+  const completedSteps = 7;
+  const totalSteps = 10;
+  const percentage = (completedSteps / totalSteps) * 100;
+
+  return (
+    <Card className="p-6">
+      <div className="flex items-center gap-6">
+        <ProgressCircle
+          value={percentage}
+          size="xs"
+          color={percentage === 100 ? "success" : "primary"}
+          formatValue={() => `${completedSteps}/${totalSteps}`}
+          label="Steps"
+        />
+        <div>
+          <h3 className="font-semibold">Complete your profile</h3>
+          <p className="text-sm text-muted-foreground">
+            {100 - percentage}% remaining
+          </p>
+        </div>
+      </div>
+    </Card>
+  );
+}
+```
+
+---
+
+## Testes
+
+### Testes Unitários
+
+```tsx
+// ProgressCircle.test.tsx
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { ProgressCircle } from "./ProgressCircle";
+
+describe("ProgressCircle", () => {
+  it("renders with correct role", () => {
+    render(<ProgressCircle value={50} />);
+    expect(screen.getByRole("progressbar")).toBeInTheDocument();
+  });
+
+  it("has correct aria-valuenow", () => {
+    render(<ProgressCircle value={75} />);
+    expect(screen.getByRole("progressbar")).toHaveAttribute(
+      "aria-valuenow",
+      "75",
+    );
+  });
+
+  it("has correct aria-valuemin and aria-valuemax", () => {
+    render(<ProgressCircle value={50} />);
+    const progressbar = screen.getByRole("progressbar");
+    expect(progressbar).toHaveAttribute("aria-valuemin", "0");
+    expect(progressbar).toHaveAttribute("aria-valuemax", "100");
+  });
+
+  it("displays formatted value", () => {
+    render(<ProgressCircle value={75} />);
+    expect(screen.getByText("75%")).toBeInTheDocument();
+  });
+
+  it("displays custom formatted value", () => {
+    render(<ProgressCircle value={75} formatValue={(v) => `${v} de 100`} />);
+    expect(screen.getByText("75 de 100")).toBeInTheDocument();
+  });
+
+  it("displays label", () => {
+    render(<ProgressCircle value={75} label="Active users" />);
+    expect(screen.getByText("Active users")).toBeInTheDocument();
+  });
+
+  it("hides value when showValue is false", () => {
+    render(<ProgressCircle value={75} showValue={false} />);
+    expect(screen.queryByText("75%")).not.toBeInTheDocument();
+  });
+
+  it("has data-slot attribute", () => {
+    render(<ProgressCircle value={50} />);
+    expect(screen.getByRole("progressbar")).toHaveAttribute(
+      "data-slot",
+      "progress-circle",
+    );
+  });
+
+  it("merges custom className", () => {
+    render(<ProgressCircle value={50} className="custom-class" />);
+    expect(screen.getByRole("progressbar")).toHaveClass("custom-class");
+  });
+
+  it("clamps value between 0 and 100", () => {
+    render(<ProgressCircle value={150} />);
+    expect(screen.getByRole("progressbar")).toHaveAttribute(
+      "aria-valuenow",
+      "100",
+    );
+  });
+
+  it("handles negative value", () => {
+    render(<ProgressCircle value={-10} />);
+    expect(screen.getByRole("progressbar")).toHaveAttribute(
+      "aria-valuenow",
+      "0",
+    );
+  });
+});
+```
+
+### Testes de Acessibilidade
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe";
+
+expect.extend(toHaveNoViolations);
+
+describe("ProgressCircle accessibility", () => {
+  it("has no accessibility violations", async () => {
+    const { container } = render(
+      <ProgressCircle value={50} aria-label="Loading progress" />,
+    );
+    const results = await axe(container);
+    expect(results).toHaveNoViolations();
+  });
+
+  it("supports aria-label", () => {
+    render(<ProgressCircle value={75} aria-label="Profile completion" />);
+    expect(screen.getByRole("progressbar")).toHaveAttribute(
+      "aria-label",
+      "Profile completion",
+    );
+  });
+
+  it("supports aria-labelledby", () => {
+    render(
+      <>
+        <span id="progress-label">Loading files</span>
+        <ProgressCircle value={50} aria-labelledby="progress-label" />
+      </>,
+    );
+    expect(screen.getByRole("progressbar")).toHaveAttribute(
+      "aria-labelledby",
+      "progress-label",
+    );
+  });
+});
+```
+
+### Testes de Variantes
+
+```tsx
+describe("ProgressCircle variants", () => {
+  it.each(["xxs", "xs", "sm", "md", "lg"] as const)(
+    "renders size %s correctly",
+    (size) => {
+      render(<ProgressCircle value={50} size={size} />);
+      expect(screen.getByRole("progressbar")).toBeInTheDocument();
+    },
+  );
+
+  it.each(["default", "primary", "success", "warning", "error"] as const)(
+    "renders color %s correctly",
+    (color) => {
+      render(<ProgressCircle value={50} color={color} />);
+      expect(screen.getByRole("progressbar")).toBeInTheDocument();
+    },
+  );
+
+  it("renders half-circle shape", () => {
+    render(<ProgressCircle value={50} shape="half-circle" />);
+    expect(screen.getByRole("progressbar")).toBeInTheDocument();
+  });
+});
+```
+
+---
+
+## Roadmap / Features Futuras
+
+### ✅ Implementado
+
+- **Size variants** - 5 tamanhos (xxs, xs, sm, md, lg)
+- **Color variants** - 5 cores (default, primary, success, warning, error)
+- **Shape variants** - 2 formas (circle, half-circle)
+- **Label** - Texto descritivo no centro
+- **formatValue** - Formatação customizada do valor
+- **showValue** - Controle de visibilidade do valor
+- **strokeWidth** - Espessura customizada
+- **ARIA completo** - role, aria-valuenow, aria-valuemin, aria-valuemax, aria-label
+- **Indeterminate State** - Estado de loading contínuo com animação
+
+### Prioridade Média
+
+#### Animation Variants
+
+Animação de entrada e transição entre valores.
+
+```tsx
+// Proposta de API
+<ProgressCircle value={75} animated />
+<ProgressCircle value={75} transitionDuration={500} />
+```
+
+**Referências:** Mantine (`transitionDuration`), Chakra
+
+#### Gradient Stroke
+
+Suporte a gradiente no indicator.
+
+```tsx
+// Proposta de API
+<ProgressCircle value={75} gradient={{ from: "blue", to: "purple" }} />
+```
+
+**Referências:** Ant Design (`strokeColor` array/object)
+
+### Prioridade Baixa
+
+#### Multi-Section
+
+Múltiplas seções com cores diferentes.
+
+```tsx
+// Proposta de API (como Mantine)
+<ProgressCircle
+  sections={[
+    { value: 40, color: "cyan" },
+    { value: 25, color: "orange" },
+    { value: 15, color: "grape" },
+  ]}
+/>
+```
+
+**Referências:** Mantine (RingProgress)
+
+#### Tooltip por Seção
+
+Tooltip ao hover em cada seção.
+
+```tsx
+// Proposta de API
+<ProgressCircle
+  sections={[
+    { value: 40, color: "cyan", tooltip: "Storage" },
+    { value: 25, color: "orange", tooltip: "Cache" },
+  ]}
+/>
+```
+
+**Referências:** Mantine
+
+### Decisões de Design
+
+| Feature       | Status          | Justificativa                           |
+| ------------- | --------------- | --------------------------------------- |
+| `size`        | ✅ Implementado | 5 variantes baseadas no Figma           |
+| `shape`       | ✅ Implementado | circle + half-circle para flexibilidade |
+| `color`       | ✅ Implementado | Alinhado com tokens do design system    |
+| `label`       | ✅ Implementado | Contexto adicional para métricas        |
+| `formatValue` | ✅ Implementado | Flexibilidade na apresentação           |
+| Indeterminate | ✅ Implementado | Estado de loading contínuo com animação |
+| Gradient      | ~ Avaliar       | Pode ser feito via CSS                  |
+| Multi-section | ~ Avaliar       | Complexidade vs. uso                    |
+
+---
+
+## Referências
+
+### Design Systems Analisados
+
+| Design System     | Componente        | Documentação                                                         |
+| ----------------- | ----------------- | -------------------------------------------------------------------- |
+| **Chakra UI v3**  | ProgressCircle    | [Docs](https://chakra-ui.com/docs/components/progress-circle)        |
+| **Chakra UI v2**  | CircularProgress  | [Docs](https://v2.chakra-ui.com/docs/components/circular-progress)   |
+| **MUI**           | CircularProgress  | [Docs](https://mui.com/material-ui/react-progress/)                  |
+| **Mantine**       | RingProgress      | [Docs](https://mantine.dev/core/ring-progress/)                      |
+| **Ant Design**    | Progress (circle) | [Docs](https://ant.design/components/progress)                       |
+| **NextUI/HeroUI** | CircularProgress  | [Docs](https://www.heroui.com/docs/components/circular-progress)     |
+| **React Aria**    | ProgressBar       | [Docs](https://react-spectrum.adobe.com/react-aria/ProgressBar.html) |
+| **Fluent UI**     | Spinner           | [Docs](https://react.fluentui.dev/?path=/docs/components-spinner)    |
+| **PrimeReact**    | ProgressBar       | [Docs](https://primereact.org/progressbar/)                          |
+
+### Especificações e Padrões
+
+- [WAI-ARIA APG - Meter Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/meter/)
+- [WCAG 2.1 Success Criteria](https://www.w3.org/WAI/WCAG21/quickref/)
+- [MDN - SVG circle](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/circle)
+- [SVG stroke-dasharray](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke-dasharray)
+
+### Ferramentas Utilizadas
+
+- [CVA - Class Variance Authority](https://cva.style/docs)
+- [Tailwind CSS](https://tailwindcss.com/docs)
+- [SVG Native](https://developer.mozilla.org/en-US/docs/Web/SVG)