# Progress — Figma alignment fix spec (X.4.2 batch)

## Inputs (✓ all read)

- ✓ `figma-data/normalized/figma-mcp-cache/progress.tsx` (4915:7287, axes: theme(dark/light) × status(default/success/error/warning) × size(M/S))
- ✓ `src/canonical/Progress.vue` (wrapper)
- ✓ `src/components/Progress/Progress.vue` (impl)
- ✓ `figma-data/normalized/figma-styles.json`
- ✓ `src/design-system/translation/token-aliases.ts`
- ✓ `src/design-system/translation/prop-aliases.md`
- ✓ `src/design-system/translation/icon-aliases.ts`
- ✓ `src/tokens/variables.css`

## Mismatches by dimension

### Spacing

| Location | Canonical (impl) | Figma 真源 | Fix |
|---|---|---|---|
| `.progress` `gap` | `8px` raw | `gap-[8px]` → `--sp-xs` | use `var(--sp-xs)` |
| `.progress` `min-height` | `16px` raw | implicit (M=8 + label 16) | replace with `var(--sp-m)` (16=`--sp-m`); OR drop, since label height drives layout |
| `.progress__track` `height` size M | (`--progress-track-height: 8px` literal) | `h-[8px]` figma raw | use `var(--sp-xs)` (8=`--sp-xs`); express via domain token |
| `.progress__track` `height` size S | (`--progress-track-height: 4px` literal) | `h-[4px]` figma raw | use `var(--sp-xxs)` (4=`--sp-xxs`); express via domain token |
| `.progress__track` / `__fill` `border-radius` | `20px` raw | `rounded-[var(--radius\/xxl,20px)]` — figma uses `--r-xxl` token name but value 20px (NOT 100px in canonical scale) | **Mismatch**: canonical `--r-xxl: 100px` ≠ figma fallback 20px. Figma's `radius/xxl` token in figma library = 20 here. **Fix**: introduce domain `--progress-track-radius: 20px` (or treat as pill: `9999px` since fully rounded for any height ≤ 20px is identical). Recommend `9999px` pill — matches actual figma render and `--r-xxl: 100px` would also work for short tracks but semantically wrong. |
| `.progress__label` `width` `32px` | raw | `w-[32px]` figma raw | non-token; keep or domain `--progress-label-width: 32px` (already exists ✓ as `--progress-label-width`) |

### Color

| Location | Canonical (impl) | Figma 真源 | Fix |
|---|---|---|---|
| `--progress-track-bg` (default) | `var(--line-deep)` (post-CANONICAL-006 fix, commit fae0c04) | dark: `var(--color-type\/background\/layer_3,#262626)` → `--bg-layer3`; light: `var(--ux\/grey\/grey-4-\#dbdbdb,#dbdbdb)` → `--color-grey-4` | **MISMATCH**: canonical uses single `--line-deep` (theme-aware: dark=#353535, light=#dbdbdb). Figma uses theme-aware *but different dark color*: `--bg-layer3` (#262626) for dark, `--color-grey-4` (#dbdbdb) for light. Note canonical Progress has its own theme axis — should be theme-stable per variant. **Fix**: replace site-theme-aware `--line-deep` with theme-axis-keyed domain tokens: dark=`--color-grey-11` (#262626), light=`--color-grey-4`. (Currently canonical Progress impl ignores `theme` prop entirely for track bg — the wrapper passes theme but impl never reads it.) |
| `--progress-fill-color` (success/default) | `var(--brand)` | `var(--ux\/brand\/brand,#2fb54e)` → `--brand` | ✓ match |
| `--progress-fill-color` (error) | `var(--red)` | `var(--ux\/red\/default,#ea4233)` → `--red` | ✓ match |
| `--progress-fill-color` (warning) | `var(--orange)` | `var(--ux\/orange\/default,#f68512)` → `--orange` | ✓ match |
| `--progress-label-color` | `var(--color-grey-5)` (#cccccc) | `text-[color:var(--color-type\/text\/text_2,#ccc)]` → `--text-2` | **MISMATCH** semantic: canonical uses raw grey scale, figma uses semantic `--text-2`. **Fix**: replace with `var(--text-2)`. |

### Typography

| Location | Canonical (impl) | Figma 真源 | Fix |
|---|---|---|---|
| `.progress__label` `font-size` 12 + `line-height` 16 + `weight` 400 | 3 raw lines | `Roboto/12 tips` → `--text-style-tips` | replace with `font: var(--text-style-tips);` |

### Effect

- No shadows in figma source. Canonical has none. ✓ aligned.

### Composition

- Figma: outer flex with track box (rounded) containing fill div + label `<p>`. Canonical: same structure (`.progress__track` > `.progress__fill` + `.progress__label`). ✓ structurally aligned.
- **Mismatch**: canonical impl does NOT use the `theme` prop in CSS — wrapper passes theme but impl reads only `status` for fill color. Track bg is uniformly `--line-deep` (post-CANONICAL-006). Per figma 真源, track bg differs by `theme`. **Fix**: impl must apply `progress--dark`/`progress--light` modifier class and bind track bg accordingly.

### Variant coverage

| Axis | Figma values | Canonical | Status |
|---|---|---|---|
| theme | `dark`, `light` | wrapper passes through; impl declares but ignores in CSS | **MISSING in impl CSS** — fix required |
| status | `default`, `success`, `error`, `warning` | `'default' \| 'success' \| 'error' \| 'warning'` | ✓ match (figma `success` and `default` both green; canonical also coalesces — visual ✓) |
| size | `M`, `S` | accepts both `'M' \| 'S' \| 'm' \| 's'` and normalizes | ✓ match (lenient) |

## Token usage summary

After fix the impl file should reference only:

- Spacing: `--sp-xxs`, `--sp-xs`, `--sp-m`
- Color: `--brand`, `--red`, `--orange`, `--color-grey-4`, `--color-grey-11`, `--text-2`
- Typography: `--text-style-tips`
- Effect: none
- Domain (proposed): `--progress-track-bg-dark`, `--progress-track-bg-light`, `--progress-track-h-m`, `--progress-track-h-s`, `--progress-label-width`, `--progress-track-radius`

## Refactor scope

1. `src/components/Progress/Progress.vue` `<script setup>`:
   - Add `theme` to `:class` binding: `[progress--${normalizedSize}, progress--${theme}]`.
2. `src/components/Progress/Progress.vue` `<style scoped>`:
   - Replace `gap: 8px` with `gap: var(--sp-xs)`.
   - Replace `min-height: 16px` with `min-height: var(--sp-m)` (or remove).
   - Remove single `--progress-track-bg: var(--line-deep)` default; add per-theme:
     ```
     .progress--dark { --progress-track-bg: var(--progress-track-bg-dark); }
     .progress--light { --progress-track-bg: var(--progress-track-bg-light); }
     ```
   - Replace `--progress-label-color: var(--color-grey-5)` with `var(--text-2)`.
   - Replace track `border-radius: 20px` (and fill) with `border-radius: 9999px` (pill — matches figma render) OR `var(--progress-track-radius)` domain token.
   - Replace 3-line typography on `.progress__label` with `font: var(--text-style-tips);`.
3. `src/canonical/Progress.vue`:
   - No changes needed; passes theme prop already.
4. `src/tokens/variables.css` — add under "Derived aliases":
   ```
   /* Progress — has own theme axis, theme-stable per variant (figma 真源) */
   --progress-track-bg-dark: var(--color-grey-11);   /* #262626 */
   --progress-track-bg-light: var(--color-grey-4);   /* #dbdbdb */
   --progress-track-h-m: var(--sp-xs);               /* 8px */
   --progress-track-h-s: var(--sp-xxs);              /* 4px */
   --progress-track-radius: 9999px;                  /* pill */
   ```
5. `src/design-system/translation/prop-aliases.md`:
   - Progress not currently registered. Add to Boolean Property Aliases table for completeness (`status`, `theme`, `size` all axis matches; no booleans). Add to "枚举值命名映射" if size case-insensitive should be documented.

## Blockers / open decisions

- **CANONICAL-006 (commit fae0c04) replaced `--bg-layer3` → `--line-deep` for track**. Per figma 真源re-check, dark track bg in figma is **#262626 = `--bg-layer3` = `--color-grey-11`** (NOT `--line-deep` which dark=#353535). The CANONICAL-006 fix appears to have introduced a divergence from figma. **Recommend revisiting**: track bg should be theme-axis-stable, dark=#262626 (grey-11), light=#dbdbdb (grey-4). Document this as the rationale to override CANONICAL-006.
- Canonical impl currently fully ignores `theme` prop — visual is identical across site themes via `--line-deep` site-theme variable. Real fix is to use Progress's own theme axis as theme-stable variant.
- Border radius 20px in figma "radius/xxl" doesn't match canonical `--r-xxl: 100px`. Pragmatic fix: use `9999px` pill since track height ≤ 8.