Refactor frontend system primitives and surfaces

2026-03-09 06:15:01 +01:00
parent 3e835ee620
commit a65037e3b3
22 changed files with 1363 additions and 106 deletions
@@ -0,0 +1,139 @@
+# 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/root/media-field-picker.tsx`
+- `components/root/portfolio-projects-overview.tsx`
+- `components/root/portfolio-project-form.tsx`
+- `components/root/portfolio-categories-manager.tsx`
+- `components/root/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/root/flash-message.tsx`
+- `components/root/media-field-picker.tsx`
+- `components/root/portfolio-categories-manager.tsx`
+- `components/root/portfolio-project-form.tsx`
+- `components/root/portfolio-projects-overview.tsx`
+- `components/root/portfolio-subnav.tsx`
+- `components/root/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