🌴 Sync 2026-03-05 23:51:42

luci-theme-aurora/.dev/docs/DEVELOPMENT.md

@@ -0,0 +1,196 @@
+# Development Guide
+
+This guide covers the complete development workflow for the Aurora theme, from environment setup to building production packages.
+
+## Prerequisites
+
+- **[Node.js v20.19+](https://nodejs.org/en/download)** - JavaScript runtime
+- **pnpm** - Package manager (managed via [Corepack](https://github.com/nodejs/corepack))
+- **Tailwind CSS knowledge** - Required for styling. See [Tailwind CSS Documentation](https://tailwindcss.com/docs)
+- **Network access** - Development machine must be on the same network as your OpenWrt router
+
+## Environment Setup
+
+### 1. Clone and Install
+
+```bash
+# Clone the repository
+git clone git@github.com:eamonxg/luci-theme-aurora.git
+cd luci-theme-aurora/.dev/
+
+# Enable Corepack to manage pnpm version
+corepack enable && corepack prepare
+
+# Install dependencies
+pnpm install
+```
+
+### 2. Configure Environment
+
+```bash
+# Copy environment template
+cp .env.example .env
+
+# Edit .env and set your OpenWrt device address
+# VITE_OPENWRT_HOST=http://192.168.1.1
+```
+
+**Environment Variables:**
+
+- `VITE_OPENWRT_HOST` - Your OpenWrt LuCI web interface URL (required)
+- `VITE_DEV_HOST` - Development server host (default: `127.0.0.1`)
+- `VITE_DEV_PORT` - Development server port (default: `5173`)
+
+## Development Workflow
+
+### Start Development Server
+
+```bash
+cd luci-theme-aurora/.dev/
+pnpm dev
+```
+
+The development server will start at `http://127.0.0.1:5173` and proxy requests to your OpenWrt device.
+
+**How Vite Proxy Works:**
+
+The Vite development server uses middleware to rewrite local requests to serve CSS/JS resources from your development environment instead of the router. This enables live editing without deploying to the router. For detailed implementation, see `vite.config.ts`.
+
+**Key proxy behaviors:**
+
+1. Proxies `/cgi-bin` and `/luci-static` requests to OpenWrt device
+2. Uses middleware (`createLocalServePlugin`) to rewrite request paths for CSS and JS files
+3. CSS requests to `/luci-static/aurora/main.css` are rewritten to serve from `.dev/src/media/main.css`
+4. JS file requests are served directly from `.dev/src/resource/` with middleware reading and returning file content
+5. Injects Vite HMR client into proxied HTML responses for live reload support
+6. Redirects `/` to `/cgi-bin/luci` for proper routing
+
+### Code Style and Formatting
+
+This project uses **Prettier** for code formatting with automatic formatting on save.
+
+**Prettier Configuration:**
+
+- Located in `.prettierrc`
+- VS Code settings in `.vscode/settings.json` enable format-on-save for CSS and JS files
+- Uses `prettier-plugin-tailwindcss` to sort Tailwind CSS classes
+
+### CSS Nesting Support
+
+Thanks to **lightningcss**, you can freely use [CSS Nesting syntax](https://drafts.csswg.org/css-nesting/) in your stylesheets. The build process automatically compiles nested CSS into flat, browser-compatible format.
+
+This will be compiled to standard CSS that works in all browsers.
+
+### LuCI JavaScript API
+
+For LuCI-specific JavaScript development, refer to the official API documentation:
+
+- [LuCI JavaScript API Reference](http://openwrt.github.io/luci/jsapi/index.html)
+
+### Live Reload Behavior
+
+- **CSS changes**: Trigger full page reload via custom HMR handler
+- **JS changes**: Trigger full page reload via custom HMR handler
+- **Template changes** (`.ut` files): **Require building a new package and installing it on the router**
+
+## Building for Production
+
+### Build Command
+
+```bash
+cd luci-theme-aurora/.dev/
+pnpm build
+```
+
+This compiles all assets to the production directory `htdocs/luci-static/`, which is used by LuCI during OpenWrt package compilation.
+
+**Build Output:**
+
+```
+htdocs/luci-static/
+├── aurora/
+│   ├── main.css           # Minified CSS (via lightningcss)
+│   ├── fonts/             # Web fonts (Lato)
+│   └── images/            # Logo assets
+└── resources/
+    ├── menu-aurora.js     # Menu configuration (minified via Terser)
+    └── view/aurora/
+        └── sysauth.js     # Login page view (minified via Terser)
+```
+
+**Build Process:**
+
+1. Vite builds CSS entry point (`src/media/main.css`)
+2. Custom PostCSS plugin removes `@layer` at-rules for OpenWrt compatibility
+3. Custom Vite plugin (`luci-js-compress`) minifies JS files via Terser
+4. Static assets copied from `.dev/public/aurora/`
+
+## Package Compilation
+
+### Via GitHub Actions
+
+1. Commit your changes to the repository
+2. Manually trigger the GitHub Actions workflow
+3. The workflow will compile the theme package (.ipk/.apk files)
+
+**Workflow File:** `.github/workflows/build-and-release-aurora.yml`
+
+## Directory Structure
+
+```
+luci-theme-aurora/
+├── .dev/                           # Development environment
+│   ├── docs/                       # Project documentation
+│   │   ├── changelog/              # Version changelogs
+│   │   └── DEVELOPMENT.md          # Development guide (this file)
+│   ├── public/aurora/              # Public static assets
+│   │   ├── fonts/                  # Web fonts (Lato)
+│   │   └── images/                 # Theme images
+│   ├── scripts/                    # Build scripts
+│   │   └── clean.js                # Build cleanup utility
+│   ├── src/                        # Source code
+│   │   ├── assets/icons/           # SVG icons
+│   │   ├── media/                  # CSS entry points
+│   │   │   └── main.css            # Main stylesheet (Tailwind CSS)
+│   │   └── resource/               # JavaScript resources
+│   │       ├── view/               # LuCI view components
+│   │       └── menu-aurora.js      # Menu logic
+│   ├── .env.example                # Environment variables template
+│   ├── .prettierrc                 # Prettier configuration
+│   ├── package.json                # Node.js dependencies
+│   ├── pnpm-lock.yaml              # pnpm lock file
+│   └── vite.config.ts              # Vite configuration with custom plugins
+├── .github/                        # GitHub configuration
+│   ├── ISSUE_TEMPLATE/             # Issue templates
+│   └── workflows/                  # GitHub Actions workflows
+├── .vscode/                        # VS Code workspace settings
+│   └── settings.json               # Auto-format on save settings
+├── htdocs/luci-static/             # Build output (generated by Vite)
+│   ├── aurora/                     # Theme CSS and assets
+│   │   ├── fonts/                  # Built font files
+│   │   ├── images/                 # Built images
+│   │   └── main.css                # Compiled CSS
+│   └── resources/                  # Built JavaScript modules
+│       ├── view/                   # Minified view components
+│       └── menu-aurora.js          # Minified menu logic
+├── root/etc/uci-defaults/          # OpenWrt system integration
+│   └── 30_luci-theme-aurora        # Theme auto-setup script
+├── ucode/template/themes/aurora/   # LuCI ucode templates
+│   ├── header.ut                   # Header template
+│   ├── footer.ut                   # Footer template
+│   └── sysauth.ut                  # Login page template
+├── LICENSE                         # Apache License 2.0
+├── Makefile                        # OpenWrt package Makefile
+├── README.md                       # English documentation
+└── README_zh.md                    # Chinese documentation
+```
+
+## Tools and Technologies
+
+- **[Tailwind CSS v4](https://tailwindcss.com/)** - Utility-first CSS framework
+- **[Vite](https://vitejs.dev/)** - Build tool and development server
+  **[pnpm](https://pnpm.io/)** - Fast, disk space efficient package manager
+- **[lightningcss](https://lightningcss.dev/)** - CSS minifier
+- **[Terser](https://terser.org/)** - JavaScript minifier
+- **[Prettier](https://prettier.io/)** - Code formatter
+- **[prettier-plugin-tailwindcss](https://github.com/tailwindlabs/prettier-plugin-tailwindcss)** - Tailwind class sorting

luci-theme-aurora/.dev/docs/changelog/v0.10.0.md

@@ -0,0 +1,14 @@
+## What's Changed
+
+### New Features
+
+- **Floating Quick Navigation**: Added a floating toolbar for shortcuts with custom config, persistent state, and smooth animations
+- **Custom Logo Support**: Enabled configuration for custom theme logos
+
+### Other Improvements
+
+- **Browser Titles**: The browser tab now correctly shows the current page name.
+- **UI Polish**: Centered mega-menu layout, unified button styles, and standardized arrow icons
+- **Design System**: Improved Dark Mode color contrast and simplified design tokens
+- **Fixes**: Resolved DHCP Leases table overflow, fixed missing menu items in titles, and corrected network interface styling
+- For remaining changes, see the [full changelog](https://github.com/eamonxg/luci-theme-aurora/compare/v0.9.0_beta...v0.10.0)

luci-theme-aurora/.dev/docs/changelog/v0.11.0.md

@@ -0,0 +1,20 @@
+## What's Changed
+
+### New Features
+
+- **Login Page**: Enhanced styling and layout with support for displaying the brand logo.
+- **Customization**: Added support for switching between multiple theme styles, configurable max width, and custom component colors.
+- **Form Enhancements**: Added info icons to form fields and aligned form labels.
+- **Internationalization**: Added i18n support for tab page titles.
+
+### Other Improvements
+
+- **Design System**: Refactored color variables and redesigned design tokens, reducing build size from 240KB to 193KB.
+- **Animations**: Optimized the floating toolbar collapse animation.
+- **Fixes**:
+  - Fixed Channel Analysis chart rendering (#29).
+  - Fixed vertical alignment of loader icon and text in table placeholder rows.
+- **Compatibility**:
+  - Adapted the Overview hide/show button to upstream DOM changes.
+  - Resolved table styling (rounded corners, duplicate columns) to adapt to upstream changes.
+- For remaining changes, see the [full changelog](https://github.com/eamonxg/luci-theme-aurora/compare/v0.10.0...v0.11.0)

luci-theme-aurora/.dev/docs/changelog/v0.5.0_beta.md

@@ -0,0 +1,21 @@
+## v0.5.0_beta
+
+## Changelog
+
+### Features
+
+- Updated theme icons (logo, spinning, refresh, refresh-off, setting) for better visuals.
+- Optimized mobile display for ifacebox on Network > Interfaces page.
+- Optimized modal scrolling by setting the scroll area to the modal overlay
+- Improved table description row display on the Packages page.
+
+### Fixes
+
+- Resolved clipping issues for dropdown options by modal/header and fixed multi-select dropdown display issues.
+- Corrected alert popup positioning and resolved text content overflow.
+- Fixed modal content clipping.
+- Fixed text and icon alignment in ifacebage.
+
+### TODO
+
+- Aim for optimal compatibility with OpenWrt 24.10.

luci-theme-aurora/.dev/docs/changelog/v0.5.5_beta.md

@@ -0,0 +1,15 @@
+## v0.5.5_beta
+
+## What's Changed
+
+- Adapted **luci-mod-dashboard** for dark mode, PC, and mobile displays
+- Optimized page scroll performance on low-performance devices
+- Improved mobile display for **Network → Interfaces**
+- Enhanced mobile layout for pages like **Software** and **SQM QoS** to fix button/text overflow issues
+- Fixed horizontal scrollbar display bug
+- Fixed overflow issue in **Network → Wireless** table
+- Fixed ipk theme upgrade issue causing loss of **Aurora** option
+
+---
+
+🇨🇳 🎉 国庆假期最后一版，祝大家假期愉快，节后再见！

luci-theme-aurora/.dev/docs/changelog/v0.6.0_beta.md

@@ -0,0 +1,23 @@
+## v0.6.0_beta
+
+**Highly recommended to upgrade to the latest version**
+
+## What's Changed
+
+#### Features
+
+- Support toggling Overview homepage cards (compatible with openwrt 24.10-SNAPSHOT)
+- Added dotted underline indicator for Tooltip elements
+- Improved visual styling for `a`, `var`, `ins`, and `del` tags
+- UCI change modal now supports legend display
+- Optimized mobile table cell layout (System → Software, Network → Interfaces/Wireless/Firewall, Status → Overview)
+- Enhanced sorting indicators for sortable table headers
+- Added fallback icon for the theme
+
+#### Fixes
+
+- Fixed missing first column in Network → Firewall (Port Forwards, Traffic Rules, NAT Rules)
+- Fixed Tooltip being clipped when clicked or hovered
+- Fixed display issues in luci-mod-dashboard
+- Fixed dark mode chart background in luci-app-statistics
+- … and other minor fixes

luci-theme-aurora/.dev/docs/changelog/v0.7.0_beta.md

@@ -0,0 +1,28 @@
+## What's Changed
+
+#### New Features
+
+- **Theme Mode Switcher**: Now you can choose between Auto (follows system), Light, or Dark mode
+- **OpenWrt 24.10-SNAPSHOT Compatibility**: Added expand/collapse buttons to support the “Show/Hide Index Cards” feature on the OpenWrt 24.10-SNAPSHOT Overview page
+
+#### Improvements & Fixes
+
+- **Dropdown Menus**:
+- Fixed checkbox selection behavior when dropdown items contain both a checkbox and a label (Previously, clicking the checkbox triggered incorrect dropdown selection logic)
+- Checkbox and label elements are now properly aligned
+- Better visual feedback for options you can't select (they appear dimmed)
+- Fixed dropdown menus getting cut off on mobile screens in the bridge-vlan table
+- Dropdown icons now adapt their color based on background
+- **Forms & Inputs**:
+- Improved spacing between labels and input fields on the System → Software page
+- Radio buttons and checkboxes look more polished
+- **Mobile Experience**:
+- Better button sizes and layout on Diagnostics page
+- Fixed modal content overflowing on small screens
+- Login modal is now more compact
+- **Visual Polish**:
+- Unified scrollbar appearance throughout the interface
+- Refined theme-adaptive colors for HTML tags (`a`, `label`, `val`, `pre`)
+- **Small Fixes**:
+- Fixed tooltips that were flickering when hovering
+- Added spacing to footer to prevent content overlap

luci-theme-aurora/.dev/docs/changelog/v0.8.0_beta.md

@@ -0,0 +1,15 @@
+## What's Changed
+
+### New Features
+
+- **Redesigned Desktop Navigation**: Hover-based menus, smoother animations, unified header style
+- **Form Layout Enhancements**: Horizontal layout on desktop, vertical on mobile, improved spacing
+- **Enhanced Dynamic List**: Clearer buttons, drag animations, mobile-friendly, copy support
+- **UCI Changes**: Added numeric badge showing pending configuration changes
+
+### Other Improvements
+
+- Rebuilt dropdown logic and fixed placeholder/overflow issues
+- Refined `ifacebadge` display and dark mode styling
+- Corrected table border-radius rendering
+- For remaining changes, see the [full changelog](https://github.com/eamonxg/luci-theme-aurora/compare/v0.7.0_beta...v0.8.0_beta)

luci-theme-aurora/.dev/docs/changelog/v0.9.0_beta.md

@@ -0,0 +1,17 @@
+## **What's Changed — v0.9.0_beta**
+
+### **New Features**
+
+- Added support for [luci-app-aurora-config](https://github.com/eamonxg/luci-app-aurora-config) to customize the theme.
+- Reduced CSS bundle size to improve loading performance.
+
+---
+
+### **Improvements & Fixes**
+
+- Fixed jitter issue on top-level menu hover in the mega menu (#23).
+- Fixed table overflow issue in Mount Points (#24).
+- Fixed progress text clipping on the Package page (#26).
+- Applied semantic and status colors to buttons, tooltips, labels, and alert messages.
+- Centered alert messages both horizontally and vertically, and adjusted the spinning icon offset.
+- see the [full changelog](https://github.com/eamonxg/luci-theme-aurora/compare/v0.8.0_beta...v0.9.0_beta)