# Fadelux Child Theme — Hyvä

> **Italian luxury editorial** child theme for [fadelux.it](https://www.fadelux.it/)  
> Built on top of **Hyvä Default Theme** (Magento 2 + Alpine.js + Tailwind CSS)

---

## Design System

| Token | Value | Purpose |
|---|---|---|
| `--fl-black` | `#0A0A0A` | Base text, near-black |
| `--fl-navy` | `#1A1A2E` | Header, footer, CTA buttons |
| `--fl-ivory` | `#F5F0EB` | Page background |
| `--fl-sand` | `#E8E0D5` | Section backgrounds, image placeholders |
| `--fl-gold` | `#C8A97E` | Primary accent — hover, badges, icons |
| `--fl-gold-dk` | `#A88A5C` | Pressed states, sale prices |
| `--fl-muted` | `#7A7060` | Body text, secondary labels |
| `--fl-border` | `#D9D0C5` | Dividers, input borders |

**Fonts:**
- **Playfair Display** (display/headlines) — editorial, italic emphasis
- **Inter** (body/utility) — clean, legible

**Signature element:** Cinematic hero with editorial italic title + diagonal gradient overlay

---

## File Structure

```
fadelux-child-theme/
├── composer.json                           # Package definition
├── registration.php                        # Magento theme registration
├── theme.xml                               # Theme config (parent: Hyva/default)
├── tailwind.config.js                      # Design tokens for Tailwind
│
├── web/
│   └── css/
│       └── fadelux.css                     # Main stylesheet (all components)
│
├── Magento_Theme/
│   ├── layout/
│   │   └── default.xml                     # Injects CSS, promo bar
│   └── templates/
│       └── html/
│           ├── header.phtml                # Sticky navy header (Alpine.js)
│           ├── footer.phtml                # Editorial dark footer
│           └── promo-bar.phtml             # Gold promo bar above header
│
├── Magento_Catalog/
│   ├── layout/                             # (add catalog overrides here)
│   └── templates/product/
│       └── list/
│           └── item.phtml                  # Product card component
│
└── Magento_Theme/templates/page/
    └── homepage.phtml                      # CMS homepage template
```

---

## Prerequisites

| Dependency | Version |
|---|---|
| Magento 2 | ≥ 2.4.4 |
| Hyvä Default Theme | ^1.3 |
| PHP | ≥ 8.1 |
| Node.js | ≥ 16 |

---

## Installation

### 1. Copy theme to Magento

```bash
mkdir -p app/design/frontend/Fadelux/child
cp -r /path/to/fadelux-child-theme/* app/design/frontend/Fadelux/child/
```

### 2. Register with Composer (recommended)

```bash
# In Magento root:
composer config repositories.fadelux-child path app/design/frontend/Fadelux/child
composer require fadelux/hyva-child-theme:@dev
```

Or manually add to `composer.json`:
```json
{
    "repositories": [
        {
            "type": "path",
            "url": "app/design/frontend/Fadelux/child"
        }
    ]
}
```

### 3. Enable the theme

```bash
php bin/magento setup:upgrade
php bin/magento cache:flush
```

Then in **Admin → Content → Design → Configuration**, select `Fadelux Child` for your store view.

---

## Build CSS (Tailwind)

The child theme ships with pre-compiled `web/css/fadelux.css`. To rebuild after customizing `tailwind.config.js`:

```bash
cd app/design/frontend/Fadelux/child

# Install dependencies (first time)
npm install tailwindcss @tailwindcss/typography @tailwindcss/aspect-ratio @tailwindcss/forms

# Build (production — purged + minified)
npx tailwindcss -c tailwind.config.js \
  -i web/css/fadelux.css \
  -o web/css/fadelux.dist.css \
  --minify

# Watch (development)
npx tailwindcss -c tailwind.config.js \
  -i web/css/fadelux.css \
  -o web/css/fadelux.dist.css \
  --watch
```

> **Note:** When using Hyvä's build toolchain (`npm run build` in the theme), `tailwind.config.js` is picked up automatically. The `web/css/fadelux.css` file is then processed alongside Hyvä's own CSS pipeline.

---

## Hyvä Integration Notes

### Tailwind tokens via CSS variables
Hyvä uses CSS custom properties for `primary` and `secondary` colors. This theme overrides them:

```css
:root {
    --color-primary:         200 169 126;  /* fl-gold */
    --color-secondary:        26  26  46;  /* fl-navy */
}
```

These are in RGB space (no # prefix) so Tailwind's opacity modifier (`bg-primary/50`) works correctly.

### Alpine.js
All interactive components (header drawer, hero slider, cart badge) use Alpine.js directives that Hyvä already loads. No additional JS bundles needed.

### CMS Homepage Content
Replace the homepage CMS block content with the contents of `Magento_Theme/templates/page/homepage.phtml` **as raw HTML** in:  
**Admin → Content → Pages → Home Page**

Update the media URLs to match your actual image paths in Media Browser.

---

## Customization

### Change accent color (gold → other)
In `web/css/fadelux.css`, update `--fl-gold` and `--fl-gold-dk` in `:root`.  
In `tailwind.config.js`, update `'fl-gold'` and `'fl-gold-dk'`.

### Add/remove navigation items
Edit navigation in **Admin → Catalog → Categories** — the header template renders the Hyvä navigation block automatically.

### Promo bar text
Edit `Magento_Theme/templates/html/promo-bar.phtml` — or replace with a CMS Static Block:

```xml
<!-- In Magento_Theme/layout/default.xml, change block to: -->
<block class="Magento\Cms\Block\Block"
       name="fadelux.promo.bar"
       before="-">
    <arguments>
        <argument name="block_id" xsi:type="string">fadelux_promo_bar</argument>
    </arguments>
</block>
```

### Product card
The card template at `Magento_Catalog/templates/product/list/item.phtml` requires the parent layout block to reference it. In `Magento_Catalog/layout/catalog_category_view.xml`:

```xml
<referenceBlock name="category.products.list">
    <action method="setTemplate">
        <argument name="template" xsi:type="string">
            Magento_Catalog::product/list/item.phtml
        </argument>
    </action>
</referenceBlock>
```

---

## Performance Checklist

- [ ] Set `web/css/fadelux.css` to load with `defer` via `default.xml` `<css>` node
- [ ] Confirm Google Fonts `preconnect` links load before the stylesheet
- [ ] Run Magento's built-in CSS merge & minify (Admin → Stores → Config → Advanced → Developer)
- [ ] Enable Varnish or Full-Page Cache after styling is confirmed
- [ ] Optimise hero images to WebP (≤ 200 KB each at 1440px wide)

---

## Browser Support

Chrome 90+, Firefox 88+, Safari 14+, Edge 90+  
Mobile: iOS Safari 14+, Chrome for Android 90+

---

## License

Proprietary — © Fadelux S.r.l. All rights reserved.  
Built on [Hyvä Themes](https://hyva.io/) — subject to Hyvä license terms.