140 lines
3.4 KiB
Markdown
140 lines
3.4 KiB
Markdown
# 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
|