sass-mohfarawati/docs/frontend-system-refactor-summary.md

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:

npm run lint

Result:

• passed with no ESLint errors or warnings