sass-mohfarawati/docs/frontend-system-current-state.md

Frontend System Current State

1. UI primitive source of truth

The current primitive source of truth is the local

components/ui

layer.

Current core primitive files:

• components/ui/button.tsx
• components/ui/card.tsx
• components/ui/app-card.tsx
• components/ui/input.tsx
• components/ui/textarea.tsx
• components/ui/select.tsx
• components/ui/dialog.tsx
• components/ui/sheet.tsx
• components/ui/tabs.tsx
• components/ui/dropdown-menu.tsx
• components/ui/accordion.tsx
• components/ui/badge.tsx
• components/ui/checkbox.tsx
• components/ui/table.tsx
• components/ui/label.tsx
• components/ui/separator.tsx

Feature code currently imports these local primitives rather than importing Radix primitives directly.

2. Libraries currently used for UI, motion, icons, and class composition

UI primitives and wrappers currently used:

• @radix-ui/react-accordion
• @radix-ui/react-checkbox
• @radix-ui/react-dialog
• @radix-ui/react-dropdown-menu
• @radix-ui/react-select
• @radix-ui/react-slot

Motion currently used:

• framer-motion
• tailwindcss-animate

Icons currently used:

• lucide-react

Class composition currently used:

• class-variance-authority
• clsx
• tailwind-merge

Shared helper:

• lib/utils.ts

Current helper function:

cn()

3. Current token system in use

The active token system is defined in:

• app/globals.css
• tailwind.config.ts

Current semantic color tokens exposed in Tailwind:

• background
• foreground
• card
• card-foreground
• popover
• popover-foreground
• primary
• primary-foreground
• secondary
• secondary-foreground
• muted
• muted-foreground
• accent
• accent-foreground
• destructive
• destructive-foreground
• border
• border-strong
• input
• ring
• surface.1
• surface.2
• surface.3
• surface.inverse
• brand.primary
• brand.secondary
• status.success
• status.success-soft
• status.warning
• status.warning-soft
• sidebar.*

Current shared utility usage is centered on:

• bg-card
• bg-background
• bg-surface-2
• text-card-foreground
• text-foreground
• text-muted-foreground
• border-border/80
• border-border/70
• border-input

There are also decorative hero tokens still present in current code:

• --hero-base
• --hero-ink
• --hero-left
• --hero-right
• --hero-bottom

4. Current radius system in use

Current radius tokens in:

• app/globals.css

are:

• --radius-surface: 24px
• --radius-nested: 16px
• --radius-pill: 9999px

Current Tailwind mappings in:

• tailwind.config.ts

are:

• rounded-surface
• rounded-nested
• rounded-pill

Current usage pattern:

• rounded-surface
  • outer surfaces and primitive containers
  • components/ui/card.tsx
  • components/ui/app-card.tsx
  • components/ui/dialog.tsx
  • components/ui/select.tsx
  • components/ui/tabs.tsx
• rounded-nested
  • controls and inner blocks
  • components/ui/button.tsx
  • components/ui/input.tsx
  • components/ui/textarea.tsx
  • components/ui/select.tsx
  • components/ui/dialog.tsx
  • components/ui/sheet.tsx
• rounded-pill
  • top-level chrome controls
  • components/layout/site-header.tsx
  • components/layout/floating-preferences.tsx

5. Current surface/card/panel rules in use

Base Card

Source:

• components/ui/card.tsx

Current base surface rule:

rounded-surface border border-border/80 bg-card text-card-foreground shadow-card

AppCard

Source:

• components/ui/app-card.tsx

Current visual levels:

• level={1}
  • border border-border/80 bg-card text-card-foreground shadow-card
• level={2}
  • border border-input bg-background text-foreground shadow-xs
• level={3}
  • border border-border/80 bg-surface-2 text-foreground shadow-panel
• level="inverse"
  • border-transparent bg-foreground text-background shadow-card

Current padding variants:

• none
• sm
  • p-4
• md
  • p-6
• lg
  • p-8

Current interactive rule:

• hover:bg-accent/30 hover:text-accent-foreground

Current feature code now reuses these levels in shared admin surfaces.

Examples:

• 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

6. Current input/button/select/dialog/sheet rules in use

Button

Source:

• components/ui/button.tsx

Current base rule:

inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-nested text-sm font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50

Current variants:

• default
  • bg-primary text-primary-foreground shadow-sm hover:bg-primary/92
• secondary
  • bg-secondary text-secondary-foreground hover:bg-secondary/90
• outline
  • border border-input bg-background hover:border-border-strong hover:bg-accent hover:text-accent-foreground
• ghost
  • text-muted-foreground hover:bg-muted hover:text-foreground
• link
  • rounded-none text-primary underline-offset-4 hover:underline
• destructive
  • bg-destructive text-destructive-foreground hover:bg-destructive/90

Input

Source:

• components/ui/input.tsx

Current rule:

flex h-10 w-full rounded-nested border border-input bg-background px-3 py-2 text-base text-foreground shadow-xs ... focus-visible:border-ring ... focus-visible:ring-ring/30

Select

Source:

• components/ui/select.tsx

Current trigger rule:

flex h-10 w-full items-center justify-between rounded-nested border border-input bg-background px-3 py-2 text-sm shadow-xs

Current content rule:

rounded-surface border border-input bg-background text-foreground shadow-panel

Current item rule:

rounded-nested ... focus:bg-accent focus:text-accent-foreground

Dialog

Source:

• components/ui/dialog.tsx

Current overlay rule:

fixed inset-0 z-50 bg-foreground/30 backdrop-blur-sm

Current content rule:

rounded-surface border border-border/80 bg-card p-6 text-card-foreground shadow-panel

Current close button rule:

inline-flex h-8 w-8 items-center justify-center rounded-nested text-muted-foreground hover:bg-accent hover:text-foreground

Sheet

Source:

• components/ui/sheet.tsx

Current overlay rule matches Dialog:

fixed inset-0 z-50 bg-foreground/30 backdrop-blur-sm

Current content rule:

border-border/80 bg-card p-6 text-card-foreground shadow-panel

Current side radius rules:

• sm:rounded-l-surface
• sm:rounded-r-surface
• rounded-b-surface
• rounded-t-surface

Tabs

Source:

• components/ui/tabs.tsx

Current list rule:

inline-flex ... gap-2 rounded-surface border border-border/80 bg-muted/40 p-1.5

Current trigger rule:

rounded-nested px-3 py-2 text-sm font-medium text-muted-foreground

Current active trigger rule:

border border-border/80 bg-background text-foreground shadow-xs

7. Current layout/container rules in use

Container

Source:

• components/layout/container.tsx

Current base rule:

mx-auto w-full px-4 sm:px-6 lg:px-8

Current size variants:

• default
  • max-w-layout
• narrow
  • max-w-narrow
• wide
  • max-w-wide
• admin
  • max-w-admin

Mapped widths from:

• app/globals.css

are:

• --container-narrow: 48rem
• --container-default: 72rem
• --container-wide: 80rem
• --container-admin: 88rem

Shared public top chrome

Current shared top controls use:

• rounded-pill
• border-border/70
• bg-background/80
• shadow-panel
• backdrop-blur-chrome

Files:

• components/layout/site-header.tsx
• components/layout/floating-preferences.tsx

Admin shell

Current admin layout still uses:

• min-h-screen bg-muted/30
• grid min-h-screen lg:grid-cols-[280px_minmax(0,1fr)]
• sticky sidebar and header
• p-4 lg:p-6

Source:

• components/dashboard/dashboard-layout.tsx

8. Current spacing rhythm in use

Current repeated spacing values:

• p-4
• p-6
• p-8
• px-3 py-2
• px-4 py-2
• px-4 py-3
• px-4 py-4
• gap-2
• gap-3
• gap-4
• gap-6
• space-y-2
• space-y-3
• space-y-4
• space-y-6

Current primitive spacing sources:

• CardHeader
  • gap-1.5 p-6
• CardContent
  • p-6 pt-0
• AppCard padding="sm"
  • p-4
• AppCard padding="md"
  • p-6
• AppCard padding="lg"
  • p-8
• Container
  • px-4 sm:px-6 lg:px-8

Current layout spacing is also built around:

• gap-section
• gap-content

from:

• tailwind.config.ts

9. Current motion rules in use

Primary motion library:

• framer-motion

State animation utility layer:

• tailwindcss-animate

Current motion patterns:

• reveal-on-scroll wrapper
  • components/motion-fade.tsx
  • initial={{ opacity: 0, y: 20 }}
  • whileInView={{ opacity: 1, y: 0 }}
  • transition={{ duration: 0.45, delay, ease: "easeOut" }}
• shared overlay and disclosure state classes
  • components/ui/dialog.tsx
  • components/ui/sheet.tsx
  • components/ui/select.tsx
  • components/ui/dropdown-menu.tsx
  • components/ui/accordion.tsx
• animated navigation chrome
  • components/layout/site-header.tsx

10. Current icon rules in use

Current icon library:

• lucide-react

Current rule:

icons are imported directly from

lucide-react

and used through local primitives or feature components.

Examples:

• components/ui/dialog.tsx
• components/ui/select.tsx
• components/layout/site-header.tsx
• components/theme-toggle.tsx
• components/root/portfolio-project-form.tsx

No second React icon library is present in:

• package.json

11. Current forbidden drift or remaining transitional areas, if any

The shared primitive layer is currently tokenized.

Remaining transitional or non-shared drift still present in the codebase:

• public atmospheric and hero visuals still use route-specific raw gradients and rgba(...)
  • components/layout/home-hero.tsx
  • components/layout/site-ambient-backdrop.tsx
  • components/layout/hero-atmosphere.tsx
  • components/layout/site-logo.tsx
• coming-soon still uses older translucent raw chrome rules
  • app/[locale]/coming-soon/page.tsx
• some public route-level content blocks still use route-local classes instead of shared primitives
  • app/[locale]/(site)/portfolio/page.tsx
  • app/[locale]/(site)/portfolio/[slug]/page.tsx
• one custom dark preview surface remains in current admin code
  • components/root/site-settings-form.tsx
  • bg-slate-950
  • text-white/55
  • text-white/60
• some admin and public cards still use Card with local class overrides instead of AppCard
  • app/root/page.tsx
  • components/dashboard/dashboard-card.tsx

These are current areas in the repository, but they are not the shared-system rules.

12. Codex rules derived from the current system

• Use components/ui as the primitive source of truth.
• Use cn() from lib/utils.ts for class composition.
• Use semantic tokens already defined in app/globals.css and mapped in tailwind.config.ts.
• Use Card as the base surface primitive.
• Use AppCard when feature code needs explicit shared surface levels.
• Use AppCard level={1} for primary card surfaces.
• Use AppCard level={2} for nested panels and inner blocks.
• Use AppCard level={3} for elevated grouped panels.
• Use rounded-surface, rounded-nested, and rounded-pill as the shared radius system.
• Use Input, Textarea, Select, Dialog, Sheet, and Tabs from components/ui instead of rebuilding those patterns in feature code.
• Use Container for width and horizontal padding rules.
• Use lucide-react for icons.
• Use framer-motion for custom motion and tailwindcss-animate for primitive state transitions.
• Do not treat route-specific hero visuals or transitional raw blocks as shared-system primitives.