kr-phim/.agents/frontend-design.md

# Frontend Design and Styling Guidelines

This guide defines the design system, styling philosophy, and component design patterns used in the CineK (kr-phim) project. All AI agents MUST read and strictly adhere to these guidelines when modifying or creating any frontend UI.

---

## 1. Core Philosophy: Premium & Dynamic Aesthetics
CineK is a premium movie streaming website. Simple, generic, or plain-looking user interfaces are NOT acceptable. Every UI must feel premium, modern, and interactive:
- **Curated Palettes**: Avoid generic primary colors (e.g. basic `#0000ff` blue or `#ff0000` red). Instead, use the project's tailored palettes (CineK yellow, dark/slate neutrals).
- **Responsive & Alive**: Every interactive element (buttons, cards, inputs, tabs) must have hover/active states with smooth transitions.
- **Glassmorphism & Gradients**: Use smooth, semi-transparent overlays (`bg-white/5` with `backdrop-blur-md`) and linear-gradient background shapes on dark elements to create depth.
- **Typography Hierarchy**: Maintain strict typographical hierarchies using clean sans-serif typography (`Be Vietnam Pro`). Avoid raw default sans-serif when possible.

---

## 2. Global Typography & Styling Variables
We use **Tailwind CSS v4** and customize the theme variables inside `app/assets/css/main.css`:

### Font
- **Primary Font**: `"Be Vietnam Pro"`, ui-sans-serif, system-ui, sans-serif
- Imported globally via Google Fonts API.

### Primary Color Palette (CineK Yellow)
Our brand color is a warm yellow:
- `--color-cinek-50`: `#fefce8`
- `--color-cinek-100`: `#fef9c3`
- `--color-cinek-300`: `#fde047`
- `--color-cinek-400`: `#facc15`
- `--color-cinek-500`: `#eab308` (Primary brand color)
- `--color-cinek-950`: `#422006`

### Theme Backgrounds
- **Dark Mode Background**: `#0E111A` (Body background for the main streaming portal)
- **Admin Light Mode Background**: `#f8fafc` (Body background for light administration views)

---

## 3. Utility Class Design System
A central set of class conventions is defined in `main.css`. Always prefer these predefined styles over ad-hoc Tailwind classes to keep the markup clean and maintain visual consistency.

| Utility Class | Description | Standard Usage |
|---|---|---|
| `.admin-page` | Layout wrapper for admin views | `<div class="admin-page">` |
| `.admin-card` | Container with borders and hover state | `<div class="admin-card">` |
| `.admin-card-gradient` | Container with subtle top highlights | `<div class="admin-card-gradient">` |
| `.admin-input` | Standard styling for input fields (height: 11) | `<input class="admin-input" />` |
| `.admin-input-sm` | Compact input fields for dense tables | `<input class="admin-input-sm" />` |
| `.admin-btn-primary` | Main action buttons (brand blue/yellow) | `<button class="admin-btn-primary">` |
| `.admin-btn-secondary` | Muted/Bordered secondary actions | `<button class="admin-btn-secondary">` |
| `.admin-btn-danger` | Alert/Destructive actions | `<button class="admin-btn-danger">` |
| `.admin-badge` | Visual badges (status, tags) | `<span class="admin-badge">` |
| `.admin-label` | Small uppercase tracker label for inputs | `<label class="admin-label">` |
| `.admin-section-title` | Title for primary view section headings | `<h1 class="admin-section-title">` |
| `.admin-section-subtitle` | Context/Subtitle beneath a section title | `<p class="admin-section-subtitle">` |
| `.admin-num` | Numbers/Metrics (tabular-nums font) | `<span class="admin-num">` |

---

## 4. Dark vs. Light Theme Rules (Admin Layout)
The admin layout uses an `.admin-light` wrapper that forces a crisp enterprise look. Do not hardcode dark utilities (`dark:...`) unless you specifically want dark behavior in both modes.

In `.admin-light` mode, the global styles in `main.css` are overridden:
- Global text colors mapping to `text-slate-400`, `text-zinc-500`, etc., are forced to darker shades (`#475569` or `#334155`) to comply with accessibility standards (contrast ratios).
- Cards become solid white, backgrounds become light gray-blue (`#f8fafc`), and border properties adapt to `#e2e8f0`.

When coding admin components:
- **Never** use light-gray text on a white background. Ensure headings are `#0f172a` (Slate 900) and descriptions are `#334155` (Slate 700).
- Input placeholders must remain readable (`#94a3b8` - Slate 400).

---

## 5. UI Components & Icon Conventions
- **Icons**: Do not write raw `<svg>` tags. Always use the built-in `<AppIcon>` component. This wraps FontAwesome icons securely.
  - Usage: `<AppIcon name="film" class="size-5" />`
  - Allowed names conform to common Lucide / FontAwesome names (e.g. `home`, `film`, `users`, `settings`, `x`, `log-out`, `menu`).
- **Sliders & Carousels**: Always use the **Swiper** library (`swiper` dependencies are present in `package.json`).
- **Scrollbars**: Apply the `.admin-scrollbar` utility class for sleek custom scrollbars in scrollable panels or tables.
- **Animations**: Use predefined transitions like `.hero-fade-enter-active` or Vue transitions with `name="modal-fade"` / `name="sidebar-fade"` for smooth entrance and exit animations.

---

## 6. Official Anthropic / Claude Code Frontend Design Principles
Adopt the mindset of a design lead at a specialized studio. Avoid generic, templated default designs. Follow these exact rules from the Claude Code `frontend-design` plugin:

### Grounding in the Subject
- State one concrete subject, audience, and the view's single job before coding.
- Match typography, color, and layout to the specific cinematic context of the Korean movie database (CineK).

### Visual & Typography Guidelines
- **Hero/Header**: Make the hero element a "thesis" presenting the most characteristic thing about the movie database. Avoid the templated "big number with a small label + gradient accent" unless it truly fits.
- **Typography Pairing**: Pair display and body fonts deliberately. Do not let text act as a neutral vehicle; make the type treatment a memorable part of the design.
- **Structure**: Numbering, badges, dividing lines, and labels must represent real structure and sequence in the movie database. Do not use numbers (like 01 / 02 / 03) unless ordering carries essential information.
- **Motion**: Use motion deliberately (loading animations, scroll reveals, hover interactions). Avoid cluttered animations that scream "AI-generated". Less is more.

### Process: The Two-Pass Workflow
1. **Pass 1: Brainstorming**: First define a token system.
   - **Color**: 4–6 named hex values.
   - **Type**: Choose faces for the different typography roles.
   - **Layout**: Draft a layout concept with one-sentence descriptions.
   - **Signature**: Define the single unique element this view will be remembered by.
2. **Pass 2: Critique & Build**: Review the plan against generic templates. If it looks like a generic SaaS dashboard, revise it. Once validated, build the code exactly following the plan.

### Restraint & Copywriting
- **Restraint**: Spend boldness in one place (the signature element). Keep everything else clean and disciplined.
- **Copywriting**: Words are design material. Write from the user's side of the screen using active voice.
  - E.g., "Save changes," not "Submit".
  - Empty states should be invitations to act, and errors should explain what went wrong and how to fix it without being vague.