# Frontend System Refactor Summary

## Scope

This refactor was applied directly in the codebase.

It focused on:

- radius normalization
- primitive normalization
- removing arbitrary visual drift from shared UI
- standardizing shared surface patterns
- fixing the false abstraction in `components/ui/app-card.tsx`

## Architecture Preserved

- `components/ui` remains the primitive source of truth
- `cn()` in `lib/utils.ts` remains unchanged and is still the shared class composition helper
- existing semantic token naming remains unchanged
- no new UI library was introduced

Current primitive layer remains in:

- `components/ui/button.tsx`
- `components/ui/card.tsx`
- `components/ui/dialog.tsx`
- `components/ui/select.tsx`
- `components/ui/sheet.tsx`
- `components/ui/tabs.tsx`
- `components/ui/app-card.tsx`

## What Changed

### 1. Radius normalization

Shared system areas were normalized toward:

- `rounded-surface`
- `rounded-nested`
- `rounded-pill`

This removed inconsistent `rounded-md` and `rounded-lg` usage from the shared admin and primitive system areas.

### 2. Primitive normalization

The following primitives were aligned with the project token system:

- `components/ui/dialog.tsx`
- `components/ui/sheet.tsx`
- `components/ui/tabs.tsx`

Changes included:

- tokenized surface colors
- tokenized borders
- tokenized radius
- tokenized shadows
- unified close button treatment in `dialog` and `sheet`

### 3. Shared UI drift removal

Raw visual values were replaced with semantic tokens in:

- `components/layout/site-header.tsx`
- `components/layout/floating-preferences.tsx`
- `app/[locale]/(site)/page.tsx`

This removed raw usage patterns such as:

- hardcoded white/black alpha surfaces
- raw `rgba(...)` shadows
- raw `text-[hsl(...)]` color usage for shared controls

### 4. Shared surface standardization

Repeated nested panels and stat blocks in feature code were moved toward shared local primitives, especially `AppCard`.

Refactored areas include:

- `components/admin/media-field-picker.tsx`
- `components/admin/portfolio-projects-overview.tsx`
- `components/admin/portfolio-project-form.tsx`
- `components/admin/portfolio-categories-manager.tsx`
- `components/admin/site-settings-form.tsx`

### 5. False abstraction fixed

`components/ui/app-card.tsx` previously declared multiple levels where `level 1` and `level 2` were visually identical.

That was corrected.

Current `AppCard` levels are now meaningfully distinct:

- `level 1`
  - `bg-card`
  - `shadow-card`
- `level 2`
  - `bg-background`
  - `border-input`
  - `shadow-xs`
- `level 3`
  - `bg-surface-2`
  - `shadow-panel`
- `inverse`
  - preserved as contrast surface

## Files Updated

- `app/[locale]/(site)/page.tsx`
- `app/root/media/page.tsx`
- `app/root/page.tsx`
- `components/dashboard/dashboard-card.tsx`
- `components/dashboard/dashboard-layout.tsx`
- `components/layout/floating-preferences.tsx`
- `components/layout/site-header.tsx`
- `components/admin/flash-message.tsx`
- `components/admin/media-field-picker.tsx`
- `components/admin/portfolio-categories-manager.tsx`
- `components/admin/portfolio-project-form.tsx`
- `components/admin/portfolio-projects-overview.tsx`
- `components/admin/portfolio-subnav.tsx`
- `components/admin/site-settings-form.tsx`
- `components/ui/app-card.tsx`
- `components/ui/dialog.tsx`
- `components/ui/sheet.tsx`
- `components/ui/tabs.tsx`
- `components/ui/ui-kit-showcase.tsx`

## Validation

Validation run:

```bash
npm run lint
```

Result:

- passed with no ESLint errors or warnings