246 lines
5.9 KiB
Markdown
246 lines
5.9 KiB
Markdown
---
|
|
name: mohfarawati-frontend-system
|
|
description: Enforce the project's frontend architecture and UI system when implementing or modifying frontend code.
|
|
---
|
|
|
|
# Frontend System
|
|
|
|
This skill ensures that all frontend work follows the established UI architecture and design system used in this project.
|
|
|
|
The system is defined by the real implementation in the codebase, not by external design assumptions.
|
|
|
|
## Source of truth
|
|
|
|
The current system is defined by:
|
|
|
|
- `docs/frontend-system-current-state.md`
|
|
- `components/ui/*`
|
|
- `components/layout/*`
|
|
- `lib/utils.ts`
|
|
- `app/globals.css`
|
|
- `tailwind.config.ts`
|
|
|
|
These files define the project's UI primitives, tokens, layout rules, and styling system.
|
|
|
|
## Primitive architecture
|
|
|
|
All shared UI must originate from the local primitive layer.
|
|
|
|
Primary primitives live in:
|
|
|
|
`components/ui`
|
|
|
|
Examples include:
|
|
|
|
- Button
|
|
- Card
|
|
- AppCard
|
|
- Input
|
|
- Textarea
|
|
- Select
|
|
- Dialog
|
|
- Sheet
|
|
- Tabs
|
|
- DropdownMenu
|
|
- Accordion
|
|
- Badge
|
|
- Checkbox
|
|
- Table
|
|
- Label
|
|
- Separator
|
|
|
|
Feature code must reuse these primitives rather than reimplementing their behavior.
|
|
|
|
If new shared UI behavior is required, extend the primitive layer instead of bypassing it.
|
|
|
|
## Class composition
|
|
|
|
Use the project's shared helper:
|
|
|
|
`cn()`
|
|
|
|
from:
|
|
|
|
`lib/utils.ts`
|
|
|
|
for class composition.
|
|
|
|
Variant logic should use:
|
|
|
|
`class-variance-authority (cva)`
|
|
|
|
when the primitive already exposes variants.
|
|
|
|
## Allowed libraries
|
|
|
|
Frontend code may use only the libraries already present in the system.
|
|
|
|
UI primitives:
|
|
- `@radix-ui/react-*` through local primitives
|
|
|
|
Styling:
|
|
- `tailwindcss`
|
|
|
|
Class composition:
|
|
- `class-variance-authority`
|
|
- `clsx`
|
|
- `tailwind-merge`
|
|
|
|
Motion:
|
|
- `framer-motion`
|
|
- `tailwindcss-animate`
|
|
|
|
Icons:
|
|
- `lucide-react`
|
|
|
|
Do not introduce additional UI frameworks or icon libraries.
|
|
|
|
## Token system
|
|
|
|
Styling must rely on the semantic token layer defined in:
|
|
|
|
- `app/globals.css`
|
|
- `tailwind.config.ts`
|
|
|
|
Prefer semantic tokens over raw color values.
|
|
|
|
Shared UI must not introduce new arbitrary color values when tokens already exist.
|
|
|
|
## Radius system
|
|
|
|
The project uses a shared radius token system.
|
|
|
|
Approved radius token categories include:
|
|
|
|
- surface radius
|
|
- nested element radius
|
|
- pill radius
|
|
|
|
These tokens are mapped in Tailwind and must be used for shared UI.
|
|
|
|
Shared components should not introduce arbitrary radius values.
|
|
|
|
## Surface and card system
|
|
|
|
Shared surfaces should follow the established card system.
|
|
|
|
Primary shared surfaces originate from:
|
|
|
|
- `Card`
|
|
- `AppCard`
|
|
|
|
These primitives define the canonical surface styles used throughout the application.
|
|
|
|
Feature code should not duplicate card styling directly.
|
|
|
|
Instead, reuse these primitives or extend them where necessary.
|
|
|
|
## Layout system
|
|
|
|
Shared layout constraints should use the project's container system.
|
|
|
|
The container primitive defines width limits and horizontal padding behavior.
|
|
|
|
Container variants include categories such as:
|
|
|
|
- default layout width
|
|
- narrow content width
|
|
- wide layout width
|
|
- admin layout width
|
|
|
|
Layout code should reuse the container primitive rather than defining ad-hoc layout wrappers.
|
|
|
|
## Spacing rhythm
|
|
|
|
The project uses a consistent spacing rhythm.
|
|
|
|
Common spacing categories include:
|
|
|
|
- surface padding
|
|
- component internal spacing
|
|
- layout gaps
|
|
- vertical content spacing
|
|
|
|
Spacing values should remain consistent with the existing system used in primitives and layout components.
|
|
|
|
Avoid introducing arbitrary spacing values for shared components.
|
|
|
|
## Motion system
|
|
|
|
Motion is implemented through two layers.
|
|
|
|
Custom motion:
|
|
- `framer-motion`
|
|
|
|
Primitive state transitions:
|
|
- `tailwindcss-animate`
|
|
|
|
Before introducing new motion patterns, inspect existing motion components and reuse their behavior when possible.
|
|
|
|
## Icon system
|
|
|
|
The project uses a single icon library:
|
|
|
|
- `lucide-react`
|
|
|
|
Icons should be imported from this library only.
|
|
|
|
Do not introduce additional icon libraries.
|
|
|
|
## Arbitrary Tailwind values
|
|
|
|
Arbitrary Tailwind values are not globally forbidden.
|
|
|
|
They may be used when required for:
|
|
|
|
- layout-specific grid definitions
|
|
- rare content sizing constraints
|
|
- typography fitting adjustments
|
|
- one-off layout edge cases not covered by tokens
|
|
|
|
However, arbitrary values must not replace the shared token system.
|
|
|
|
They should not be used for shared-system styling when project tokens already exist, especially for categories such as:
|
|
|
|
- radius
|
|
- colors
|
|
- shadows
|
|
- borders
|
|
- shared surface styling
|
|
|
|
When arbitrary values are used, they should remain narrow in scope and justified by layout or typography needs.
|
|
|
|
## Forbidden patterns
|
|
|
|
The following patterns must be avoided:
|
|
|
|
- introducing a new UI framework
|
|
- bypassing the local primitive layer when an equivalent primitive already exists
|
|
- creating feature-level implementations of components that already exist in `components/ui`
|
|
- importing Radix primitives directly in feature code when a local wrapper exists
|
|
- introducing raw styling for shared UI surfaces when tokenized styles already exist
|
|
- creating duplicate design systems
|
|
- adding styling abstractions that conflict with the existing token system
|
|
|
|
## Transitional areas
|
|
|
|
Some files still contain transitional visual code.
|
|
|
|
These areas must not be treated as canonical UI system references for new work.
|
|
|
|
Examples include decorative hero components, experimental visual effects, or legacy route-level styling.
|
|
|
|
When implementing new UI, prefer primitives and tokens defined in the main system rather than copying patterns from transitional files.
|
|
|
|
## Implementation guidance for Codex
|
|
|
|
When implementing frontend code:
|
|
|
|
1. Inspect existing primitives before writing new UI.
|
|
2. Reuse primitives from `components/ui`.
|
|
3. Prefer semantic tokens over raw styling.
|
|
4. Follow the established radius, surface, spacing, and container systems.
|
|
5. Reuse motion patterns before introducing new ones.
|
|
6. Keep new UI aligned with the current frontend architecture.
|
|
|
|
If a requested UI does not fit the current primitives, extend the primitive layer rather than bypassing it. |