From 09bcf6129f9708e923db5440d0082702e951dd55 Mon Sep 17 00:00:00 2001 From: Ltdaaa Date: Fri, 5 Jun 2026 20:33:44 +0800 Subject: [PATCH 01/10] docs: add aura skin redesign spec --- .../2026-06-05-openless-aura-skin-design.md | 254 ++++++++++++++++++ 1 file changed, 254 insertions(+) create mode 100644 docs/superpowers/specs/2026-06-05-openless-aura-skin-design.md diff --git a/docs/superpowers/specs/2026-06-05-openless-aura-skin-design.md b/docs/superpowers/specs/2026-06-05-openless-aura-skin-design.md new file mode 100644 index 00000000..48d23ed5 --- /dev/null +++ b/docs/superpowers/specs/2026-06-05-openless-aura-skin-design.md @@ -0,0 +1,254 @@ +# OpenLess Aura Skin Design + +## Goal + +Refresh the OpenLess desktop UI by borrowing the visual language of the reference HTML at `iframe-export-1779865710530(1).html` while preserving OpenLess's current information architecture, page density, and reading comfort. + +This is a skin redesign, not a product redesign. + +## Design Intent + +The target look should feel more premium, sculpted, and technical without becoming dark, noisy, or visually tiring. + +We will reuse these reference qualities: + +- larger radii and softer geometry +- frosted glass layering +- stronger typography hierarchy +- restrained monochrome palette with blue reserved for accents +- clearer separation between shell, panel, card, and utility surfaces + +We will explicitly not reuse these reference qualities: + +- animated halo or WebGL background +- dark-theme-first presentation +- login-page composition +- decorative technical labels that compete with product content +- large glow effects that reduce legibility + +## Scope + +This work changes visual skin only. + +Included: + +- app background treatment +- main shell and console framing +- sidebar navigation skin +- overview cards and list containers +- high-visibility buttons, chips, badges, and status treatments +- settings modal shell and section styling +- global tokens for radii, surface color, glass, shadows, and typography + +Excluded: + +- navigation structure +- page IA and feature grouping +- product logic, IPC, or state flow +- major layout rewrites inside functional pages +- dark mode implementation +- animations beyond subtle existing transitions + +## Recommended Approach + +Use a light-theme skin migration that concentrates changes in design tokens, the app shell, and the most visible shared surfaces. + +This approach is preferred because it: + +- gives the fastest visible transformation +- keeps implementation risk low +- preserves the current UX model +- creates a reusable foundation for later page-by-page polish + +## Visual Direction + +### Background + +Replace the current mostly flat neutral app backdrop with a quiet layered field: + +- soft warm-gray to cool-gray base +- one or two static radial highlights for depth +- no motion, glow sweep, halo, or particle treatment + +The background should support the interface rather than become the interface. + +### Shell + +The top-level OpenLess window should read as a frosted control console: + +- larger outer radii than today +- stronger edge softness +- slightly deeper shadow stack +- subtle translucent panel feel +- clearer distinction between sidebar zone and content zone while keeping them visually related + +The shell should feel continuous and premium, not like separate floating white boxes. + +### Surfaces + +Introduce a more intentional surface ladder: + +1. app backdrop +2. shell glass +3. main console panel +4. elevated cards and grouped containers +5. utility pills, chips, and compact controls + +Each level should differ through opacity, blur, border contrast, and shadow depth rather than through aggressive color changes. + +### Typography + +Adopt the reference's typographic mood without sacrificing Chinese readability. + +- primary UI font: modern sans with better personality than the current system-default feel +- mono font: reserved for version labels, technical badges, and small metadata +- page titles: larger, more deliberate, more architectural +- secondary labels: quieter and cleaner + +If external web fonts are not already part of the app, prefer safe local or bundled-friendly fallbacks rather than adding fragile runtime font dependencies. + +### Color Hierarchy + +Keep OpenLess light and readable. + +- main palette remains white, off-white, graphite, and soft gray +- blue remains the only expressive accent +- blue is used for active states, focus, selected indicators, and important actions +- avoid broad saturated areas +- avoid neon glow treatments + +## Component Strategy + +### Sidebar Navigation + +Keep the same navigation items and ordering, but restyle them to match the new shell: + +- calmer inactive state +- more tactile hover state +- stronger active pill treatment +- cleaner icon and label alignment +- better-integrated version and beta chip zone + +The sidebar should feel like part of the same industrial-glass instrument rather than a separate admin rail. + +### Overview Page + +Do not reorganize the overview information model. + +Instead: + +- give provider cards more presence +- unify stats cards into the same radius and surface system +- style charts and recent-record containers as elevated glass/solid hybrids +- improve whitespace rhythm and title hierarchy + +### Buttons, Chips, and Status + +Unify small UI affordances into one design language: + +- pill-like compact chips +- more sculpted primary buttons +- restrained secondary buttons +- status accents that rely on color and contrast, not glow + +### Settings Modal + +Retain the current settings structure and content, but reskin: + +- modal container +- section tabs or navigation surfaces +- row grouping +- toggles, chips, and button styles +- footer actions + +The modal should feel like it belongs to the same skin system as the main shell. + +## Technical Plan + +Apply the redesign through three layers. + +### 1. Global Tokens + +Update `src/styles/tokens.css` to define: + +- revised neutral palette +- revised accent ladder +- larger radius system +- updated shadow tokens +- shell and card translucency tokens +- font stack updates + +### 2. Global Chrome + +Update `src/styles/global.css` and closely related shell-level styling to define: + +- background gradients +- shell glass helpers +- optional subtle grain +- scrollbar polish +- global focus and interaction refinement + +### 3. High-Visibility Containers + +Update the shell and visible page wrappers first: + +- `src/components/FloatingShell.tsx` +- settings modal shell +- overview high-visibility containers +- shared visual wrappers where existing pages already inherit common surfaces + +This keeps the redesign cohesive while avoiding a broad page-by-page rewrite. + +## Risks and Guardrails + +### Risk: Readability Regression + +Glass and translucency can reduce legibility, especially with Chinese text. + +Guardrail: + +- keep text surfaces more opaque than the reference +- use blur as support, not as the primary effect +- preserve strong text contrast + +### Risk: Incomplete Visual Consistency + +If only the shell changes, some inner surfaces may look older than the new frame. + +Guardrail: + +- prioritize the overview page and settings modal after tokens +- rely on shared tokens so untouched pages still improve passively + +### Risk: Over-stylizing + +A direct copy of the reference would conflict with OpenLess's utilitarian desktop workflow. + +Guardrail: + +- no dark-theme conversion +- no decorative labels +- no animated background +- no major layout theatrics + +## Verification + +The redesign is successful when: + +- the app visibly echoes the reference's radii, frosted surfaces, and typographic hierarchy +- OpenLess still feels light, calm, and easy to scan +- navigation and settings behavior remain unchanged +- the overview page looks like part of the new skin instead of the old one +- there is no animated light ring or equivalent visual effect anywhere in the shell + +## Implementation Boundaries + +The first implementation pass should stop once the following are true: + +- shell background is updated +- sidebar skin is updated +- main console panel is updated +- overview cards and containers are visually aligned +- settings modal visually matches the shell + +Anything beyond that should be treated as a follow-up polish pass, not folded into the first skin migration. From 6402fb8b1fd40b9c4761c0f6c36c5ef21a166190 Mon Sep 17 00:00:00 2001 From: Ltdaaa Date: Fri, 5 Jun 2026 20:37:50 +0800 Subject: [PATCH 02/10] docs: add aura skin implementation plan --- .../plans/2026-06-05-openless-aura-skin.md | 541 ++++++++++++++++++ 1 file changed, 541 insertions(+) create mode 100644 docs/superpowers/plans/2026-06-05-openless-aura-skin.md diff --git a/docs/superpowers/plans/2026-06-05-openless-aura-skin.md b/docs/superpowers/plans/2026-06-05-openless-aura-skin.md new file mode 100644 index 00000000..97ebb636 --- /dev/null +++ b/docs/superpowers/plans/2026-06-05-openless-aura-skin.md @@ -0,0 +1,541 @@ +# OpenLess Aura Skin Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Apply an Aura-inspired visual skin to OpenLess by upgrading the shell, glass treatment, radii, typography, and overview surfaces while preserving the current information architecture and page density. + +**Architecture:** The implementation stays shallow and visual-only. It starts by adding a contract test that defines the new skin hooks, then updates global tokens and chrome, then reskins the main shell and settings modal, and finally aligns shared atoms and the overview page to the new surface system. + +**Tech Stack:** React 18, TypeScript, Vite 5, inline-style component patterns, CSS token files, Node-based contract checks + +--- + +## File Structure + +- Modify: `openless-all/app/package.json` + Purpose: register a repeatable Aura skin contract check command. +- Create: `openless-all/app/scripts/aura-skin-contract.test.mjs` + Purpose: assert the new skin tokens and shell hooks exist before visual work is considered complete. +- Modify: `openless-all/app/src/styles/tokens.css` + Purpose: replace the current light-glass token ladder with the new Aura-inspired radii, surfaces, shadows, and typography. +- Modify: `openless-all/app/src/styles/global.css` + Purpose: add the static layered background and shared shell/panel helper classes without introducing animation. +- Modify: `openless-all/app/src/components/FloatingShell.tsx` + Purpose: reskin the app shell, sidebar, version zone, and main console wrapper. +- Modify: `openless-all/app/src/components/SettingsModal.tsx` + Purpose: align the settings modal shell and left rail with the new skin system. +- Modify: `openless-all/app/src/pages/_atoms.tsx` + Purpose: make cards, buttons, pills, and page headers inherit the new radius and surface vocabulary. +- Modify: `openless-all/app/src/pages/Overview.tsx` + Purpose: make the overview page visibly match the new shell without changing its data structure. + +### Task 1: Add Aura Skin Contract Check + +**Files:** +- Create: `openless-all/app/scripts/aura-skin-contract.test.mjs` +- Modify: `openless-all/app/package.json` +- Test: `openless-all/app/scripts/aura-skin-contract.test.mjs` + +- [ ] **Step 1: Write the failing test** + +Create `openless-all/app/scripts/aura-skin-contract.test.mjs`: + +```js +import { readFile } from 'node:fs/promises'; +import assert from 'node:assert/strict'; + +const root = new URL('../', import.meta.url); + +async function read(relPath) { + return readFile(new URL(relPath, root), 'utf8'); +} + +const [tokens, globalCss, shell, settingsModal, overview] = await Promise.all([ + read('src/styles/tokens.css'), + read('src/styles/global.css'), + read('src/components/FloatingShell.tsx'), + read('src/components/SettingsModal.tsx'), + read('src/pages/Overview.tsx'), +]); + +assert.match(tokens, /--ol-shell-radius:/, 'tokens.css must define --ol-shell-radius'); +assert.match(tokens, /--ol-panel-radius:/, 'tokens.css must define --ol-panel-radius'); +assert.match(tokens, /--ol-aura-shadow:/, 'tokens.css must define --ol-aura-shadow'); +assert.match(tokens, /--ol-font-display:/, 'tokens.css must define --ol-font-display'); + +assert.match(globalCss, /\.ol-app-shell-bg\b/, 'global.css must expose .ol-app-shell-bg'); +assert.match(globalCss, /\.ol-aura-panel\b/, 'global.css must expose .ol-aura-panel'); +assert.doesNotMatch(globalCss, /@keyframes ol-aura-halo/, 'global.css must not add an animated halo'); + +assert.match(shell, /ol-app-shell-bg/, 'FloatingShell must use the app shell background class'); +assert.match(shell, /ol-aura-sidebar/, 'FloatingShell must expose an Aura sidebar hook'); +assert.match(shell, /ol-aura-panel/, 'FloatingShell must expose an Aura panel hook'); + +assert.match(settingsModal, /ol-aura-settings/, 'SettingsModal must expose an Aura settings wrapper'); +assert.match(overview, /ol-overview-hero/, 'Overview must expose a high-visibility overview surface hook'); + +console.log('Aura skin contract OK'); +``` + +- [ ] **Step 2: Register the check in `package.json`** + +Modify `openless-all/app/package.json`: + +```json +{ + "scripts": { + "dev": "vite", + "build": "tsc && vite build", + "preview": "vite preview", + "tauri": "tauri", + "check:aura-skin": "node scripts/aura-skin-contract.test.mjs", + "check:macos-capsule-spaces": "node scripts/macos-capsule-spaces-contract.test.mjs", + "check:hotkey-injection": "node scripts/check-hotkey-injection.mjs" + } +} +``` + +- [ ] **Step 3: Run the test to verify it fails** + +Run: + +```bash +npm run check:aura-skin +``` + +Expected: + +```text +AssertionError [ERR_ASSERTION]: tokens.css must define --ol-shell-radius +``` + +- [ ] **Step 4: Commit the failing test harness** + +```bash +git add openless-all/app/package.json openless-all/app/scripts/aura-skin-contract.test.mjs +git commit -m "test: add aura skin contract" +``` + +### Task 2: Replace Global Tokens and App Chrome + +**Files:** +- Modify: `openless-all/app/src/styles/tokens.css` +- Modify: `openless-all/app/src/styles/global.css` +- Test: `openless-all/app/scripts/aura-skin-contract.test.mjs` + +- [ ] **Step 1: Update the token ladder** + +Replace the current token center in `openless-all/app/src/styles/tokens.css` with the Aura skin ladder: + +```css +:root { + --ol-bg-base: #f3f4f6; + --ol-bg-elevated: #fbfbfc; + --ol-surface: rgba(255, 255, 255, 0.72); + --ol-surface-2: rgba(255, 255, 255, 0.88); + --ol-surface-solid: #ffffff; + + --ol-line: rgba(15, 23, 42, 0.08); + --ol-line-strong: rgba(15, 23, 42, 0.14); + --ol-line-soft: rgba(255, 255, 255, 0.55); + + --ol-ink: #10131a; + --ol-ink-2: #222938; + --ol-ink-3: rgba(16, 19, 26, 0.64); + --ol-ink-4: rgba(16, 19, 26, 0.42); + --ol-ink-5: rgba(16, 19, 26, 0.24); + + --ol-blue: #2f6df6; + --ol-blue-hover: #2458c8; + --ol-blue-soft: rgba(47, 109, 246, 0.10); + --ol-blue-ring: rgba(47, 109, 246, 0.22); + + --ol-shell-radius: 32px; + --ol-panel-radius: 28px; + --ol-card-radius: 22px; + --ol-pill-radius: 999px; + + --ol-aura-shadow: 0 24px 80px -32px rgba(15, 23, 42, 0.24), 0 12px 36px -18px rgba(15, 23, 42, 0.12); + --ol-aura-shadow-soft: 0 10px 30px -18px rgba(15, 23, 42, 0.16), 0 0 0 0.5px rgba(255, 255, 255, 0.55) inset; + + --ol-font-display: "Aptos", "Segoe UI Variable Display", "PingFang SC", "Microsoft YaHei", sans-serif; + --ol-font-sans: "Aptos", "Segoe UI Variable Text", "PingFang SC", "Microsoft YaHei", sans-serif; + --ol-font-mono: "JetBrains Mono", "SF Mono", "Cascadia Code", Consolas, monospace; +} +``` + +- [ ] **Step 2: Add static Aura shell helpers** + +Append shared helpers to `openless-all/app/src/styles/global.css`: + +```css +body { + background: + radial-gradient(circle at 18% 12%, rgba(255, 255, 255, 0.92), rgba(255, 255, 255, 0) 34%), + radial-gradient(circle at 86% 18%, rgba(47, 109, 246, 0.08), rgba(47, 109, 246, 0) 30%), + linear-gradient(180deg, #f6f7fa 0%, #eef1f6 100%); + color: var(--ol-ink); +} + +.ol-app-shell-bg { + background: + radial-gradient(circle at top left, rgba(255, 255, 255, 0.68), rgba(255, 255, 255, 0) 38%), + linear-gradient(180deg, rgba(255, 255, 255, 0.68), rgba(245, 247, 251, 0.58)); +} + +.ol-aura-panel { + background: var(--ol-surface); + backdrop-filter: blur(24px) saturate(150%); + -webkit-backdrop-filter: blur(24px) saturate(150%); + border: 1px solid rgba(255, 255, 255, 0.58); + box-shadow: var(--ol-aura-shadow); +} + +.ol-aura-card { + background: linear-gradient(180deg, rgba(255, 255, 255, 0.92), rgba(252, 252, 253, 0.82)); + border: 1px solid rgba(255, 255, 255, 0.74); + box-shadow: var(--ol-aura-shadow-soft); +} +``` + +- [ ] **Step 3: Run the contract check** + +Run: + +```bash +npm run check:aura-skin +``` + +Expected: + +```text +AssertionError [ERR_ASSERTION]: FloatingShell must use the app shell background class +``` + +- [ ] **Step 4: Commit the token/chrome layer** + +```bash +git add openless-all/app/src/styles/tokens.css openless-all/app/src/styles/global.css +git commit -m "feat: add aura skin tokens and chrome" +``` + +### Task 3: Reskin the Shell and Settings Modal + +**Files:** +- Modify: `openless-all/app/src/components/FloatingShell.tsx` +- Modify: `openless-all/app/src/components/SettingsModal.tsx` +- Test: `openless-all/app/scripts/aura-skin-contract.test.mjs` + +- [ ] **Step 1: Apply Aura shell hooks in `FloatingShell.tsx`** + +Update the shell wrappers in `openless-all/app/src/components/FloatingShell.tsx`: + +```tsx +
+``` + +Update the sidebar and main panel wrappers: + +```tsx +