# SkeletonLabs Upgrade Notes (December 2025)

## Overview
This document tracks the process of upgrading the SkeletonLabs UI library (from v3 to v4.7.4) within the Aether SvelteKit project. The primary goal is to resolve build issues caused by incompatibility with Svelte 5 and Tailwind CSS v4, and to integrate the updated library correctly.

## Current Status (Pre-Upgrade)
-   **SkeletonLabs Version:** v3.2.2 (as per `package.json` at commit `90ee6bb1`)
-   **Target Version:** v4.7.4
-   **Issue:** Previous attempts to upgrade SkeletonLabs to v4.7.4 resulted in a persistent, blocking build error: `[@tailwindcss/vite:generate:build] Cannot use `@variant` with unknown variant: md` originating from `node_modules/@skeletonlabs/skeleton/src/index.css`. This indicates a fundamental incompatibility in how Tailwind CSS v4 processes SkeletonLabs' pre-compiled CSS.
-   **Svelte Version:** Svelte 5 (runes mode)
-   **Tailwind CSS Version:** v4.1.10

## Phase 1: Research and Planning (No Code Changes Yet)

### Goal
Understand the required migration steps from Skeleton v3 to v4 as per official documentation, specifically to address the `@variant` build error and ensure compatibility with Svelte 5 and Tailwind CSS v4.

### Steps
1.  **Thoroughly Review Skeleton v3 to v4 Migration Guide:**
    *   **Link:** `https://www.skeleton.dev/docs/svelte/get-started/migrate-from-v3`
    *   **Action:** Read the guide carefully to identify all breaking changes related to:
        *   Tailwind CSS plugin setup in `tailwind.config.ts`.
        *   Required changes to `app.css` or any other global CSS files.
        *   Changes in component class names, especially theme-related classes (`preset-*`, `variant-*`, etc.), which could be related to the `@variant` error.
        *   The new `Dialog` component and how it replaces any previous modal-like components.
    *   **Deliverable:** Summarize the required code changes based on this guide.

2.  **Review Skeleton v4.0 Launch Discussion:**
    *   **Link:** `https://github.com/skeletonlabs/skeleton/discussions/3920`
    *   **Action:** Look for community insights, common issues, and suggested solutions related to upgrading.

3.  **Review Skeleton Dialog Documentation:**
    *   **Link:** `https://www.skeleton.dev/docs/svelte/framework-components/dialog`
    *   **Action:** Understand the API and usage of Skeleton's native dialog component, as this will be the preferred replacement for any missing `<Modal>` components.

### Expected Outcome of Phase 1
A detailed, step-by-step plan for migrating SkeletonLabs from v3 to v4, specifically targeting the resolution of the `@variant` build error and outlining the new usage of its UI components. This plan will be presented for approval before any code changes are made.

## Phase 2: Execution (After Approval)

### Steps (To be detailed after Phase 1)
1.  **Update `package.json`:** Set `@skeletonlabs/skeleton` and `@skeletonlabs/skeleton-svelte` to `4.7.4`.
2.  **Adjust `tailwind.config.ts`:** Apply changes as per migration guide (e.g., plugin configuration).
3.  **Adjust `src/app.css`:** Apply changes as per migration guide (e.g., CSS imports, custom theme definitions).
4.  **Run `npm install`**.
5.  **Run `npm run build` and `npm run dev`** to verify the build and functionality.
6.  **Replace `Modal` components:** Update existing components that used an older `<Modal>` (e.g., from `flowbite-svelte` or previous custom efforts) with Skeleton's new `Dialog` component.
7.  **Address Svelte 5 reactivity warnings:** Fix any warnings related to data handling or non-reactive updates.

## Final Decision (2025-12-08)

**Outcome:** Abandoning SkeletonLabs.

**Reasoning:**
Despite following the official migration guide and attempting various configurations, the upgrade from SkeletonLabs v3 to v4.7.4 consistently fails with a blocking build error: `[@tailwindcss/vite:generate:build] Cannot use @variant with unknown variant: md`. This error points to a fundamental incompatibility between SkeletonLabs' pre-compiled CSS and the Tailwind CSS v4 build process in this Vite project.

Given the significant time spent debugging this issue without a clear resolution path through configuration, the most pragmatic decision is to remove SkeletonLabs entirely and proceed with custom UI component implementation.

**Path Forward:**
1.  All SkeletonLabs dependencies (`@skeletonlabs/skeleton`, `@skeletonlabs/skeleton-svelte`) will be removed from `package.json`.
2.  All SkeletonLabs configurations (e.g., in `tailwind.config.ts`, `app.css`) will be removed.
3.  UI components previously provided by SkeletonLabs will be replaced with custom Svelte components styled with pure Tailwind CSS.