Fresh start: optimized code for Vercel/HF with PWA and Speed Fixes

.agent/skills/frontend-design/LICENSE.txt

@@ -0,0 +1,177 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

.agent/skills/frontend-design/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: frontend-design
+description: "Create distinctive, production-grade frontend interfaces with intentional aesthetics, high craft, and non-generic visual identity. Use when building or styling web UIs, components, pages, dashboard..."
+risk: unknown
+source: community
+date_added: "2026-02-27"
+---
+
+# Frontend Design (Distinctive, Production-Grade)
+
+You are a **frontend designer-engineer**, not a layout generator.
+
+Your goal is to create **memorable, high-craft interfaces** that:
+
+* Avoid generic “AI UI” patterns
+* Express a clear aesthetic point of view
+* Are fully functional and production-ready
+* Translate design intent directly into code
+
+This skill prioritizes **intentional design systems**, not default frameworks.
+
+---
+
+## 1. Core Design Mandate
+
+Every output must satisfy **all four**:
+
+1. **Intentional Aesthetic Direction**
+   A named, explicit design stance (e.g. *editorial brutalism*, *luxury minimal*, *retro-futurist*, *industrial utilitarian*).
+
+2. **Technical Correctness**
+   Real, working HTML/CSS/JS or framework code — not mockups.
+
+3. **Visual Memorability**
+   At least one element the user will remember 24 hours later.
+
+4. **Cohesive Restraint**
+   No random decoration. Every flourish must serve the aesthetic thesis.
+
+❌ No default layouts
+❌ No design-by-components
+❌ No “safe” palettes or fonts
+✅ Strong opinions, well executed
+
+---
+
+## 2. Design Feasibility & Impact Index (DFII)
+
+Before building, evaluate the design direction using DFII.
+
+### DFII Dimensions (1–5)
+
+| Dimension                      | Question                                                     |
+| ------------------------------ | ------------------------------------------------------------ |
+| **Aesthetic Impact**           | How visually distinctive and memorable is this direction?    |
+| **Context Fit**                | Does this aesthetic suit the product, audience, and purpose? |
+| **Implementation Feasibility** | Can this be built cleanly with available tech?               |
+| **Performance Safety**         | Will it remain fast and accessible?                          |
+| **Consistency Risk**           | Can this be maintained across screens/components?            |
+
+### Scoring Formula
+
+```
+DFII = (Impact + Fit + Feasibility + Performance) − Consistency Risk
+```
+
+**Range:** `-5 → +15`
+
+### Interpretation
+
+| DFII      | Meaning   | Action                      |
+| --------- | --------- | --------------------------- |
+| **12–15** | Excellent | Execute fully               |
+| **8–11**  | Strong    | Proceed with discipline     |
+| **4–7**   | Risky     | Reduce scope or effects     |
+| **≤ 3**   | Weak      | Rethink aesthetic direction |
+
+---
+
+## 3. Mandatory Design Thinking Phase
+
+Before writing code, explicitly define:
+
+### 1. Purpose
+
+* What action should this interface enable?
+* Is it persuasive, functional, exploratory, or expressive?
+
+### 2. Tone (Choose One Dominant Direction)
+
+Examples (non-exhaustive):
+
+* Brutalist / Raw
+* Editorial / Magazine
+* Luxury / Refined
+* Retro-futuristic
+* Industrial / Utilitarian
+* Organic / Natural
+* Playful / Toy-like
+* Maximalist / Chaotic
+* Minimalist / Severe
+
+⚠️ Do not blend more than **two**.
+
+### 3. Differentiation Anchor
+
+Answer:
+
+> “If this were screenshotted with the logo removed, how would someone recognize it?”
+
+This anchor must be visible in the final UI.
+
+---
+
+## 4. Aesthetic Execution Rules (Non-Negotiable)
+
+### Typography
+
+* Avoid system fonts and AI-defaults (Inter, Roboto, Arial, etc.)
+* Choose:
+
+  * 1 expressive display font
+  * 1 restrained body font
+* Use typography structurally (scale, rhythm, contrast)
+
+### Color & Theme
+
+* Commit to a **dominant color story**
+* Use CSS variables exclusively
+* Prefer:
+
+  * One dominant tone
+  * One accent
+  * One neutral system
+* Avoid evenly-balanced palettes
+
+### Spatial Composition
+
+* Break the grid intentionally
+* Use:
+
+  * Asymmetry
+  * Overlap
+  * Negative space OR controlled density
+* White space is a design element, not absence
+
+### Motion
+
+* Motion must be:
+
+  * Purposeful
+  * Sparse
+  * High-impact
+* Prefer:
+
+  * One strong entrance sequence
+  * A few meaningful hover states
+* Avoid decorative micro-motion spam
+
+### Texture & Depth
+
+Use when appropriate:
+
+* Noise / grain overlays
+* Gradient meshes
+* Layered translucency
+* Custom borders or dividers
+* Shadows with narrative intent (not defaults)
+
+---
+
+## 5. Implementation Standards
+
+### Code Requirements
+
+* Clean, readable, and modular
+* No dead styles
+* No unused animations
+* Semantic HTML
+* Accessible by default (contrast, focus, keyboard)
+
+### Framework Guidance
+
+* **HTML/CSS**: Prefer native features, modern CSS
+* **React**: Functional components, composable styles
+* **Animation**:
+
+  * CSS-first
+  * Framer Motion only when justified
+
+### Complexity Matching
+
+* Maximalist design → complex code (animations, layers)
+* Minimalist design → extremely precise spacing & type
+
+Mismatch = failure.
+
+---
+
+## 6. Required Output Structure
+
+When generating frontend work:
+
+### 1. Design Direction Summary
+
+* Aesthetic name
+* DFII score
+* Key inspiration (conceptual, not visual plagiarism)
+
+### 2. Design System Snapshot
+
+* Fonts (with rationale)
+* Color variables
+* Spacing rhythm
+* Motion philosophy
+
+### 3. Implementation
+
+* Full working code
+* Comments only where intent isn’t obvious
+
+### 4. Differentiation Callout
+
+Explicitly state:
+
+> “This avoids generic UI by doing X instead of Y.”
+
+---
+
+## 7. Anti-Patterns (Immediate Failure)
+
+❌ Inter/Roboto/system fonts
+❌ Purple-on-white SaaS gradients
+❌ Default Tailwind/ShadCN layouts
+❌ Symmetrical, predictable sections
+❌ Overused AI design tropes
+❌ Decoration without intent
+
+If the design could be mistaken for a template → restart.
+
+---
+
+## 8. Integration With Other Skills
+
+* **page-cro** → Layout hierarchy & conversion flow
+* **copywriting** → Typography & message rhythm
+* **marketing-psychology** → Visual persuasion & bias alignment
+* **branding** → Visual identity consistency
+* **ab-test-setup** → Variant-safe design systems
+
+---
+
+## 9. Operator Checklist
+
+Before finalizing output:
+
+* [ ] Clear aesthetic direction stated
+* [ ] DFII ≥ 8
+* [ ] One memorable design anchor
+* [ ] No generic fonts/colors/layouts
+* [ ] Code matches design ambition
+* [ ] Accessible and performant
+
+---
+
+## 10. Questions to Ask (If Needed)
+
+1. Who is this for, emotionally?
+2. Should this feel trustworthy, exciting, calm, or provocative?
+3. Is memorability or clarity more important?
+4. Will this scale to other pages/components?
+5. What should users *feel* in the first 3 seconds?
+
+---
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

.agent/skills/ui-ux-pro-max/SKILL.md

@@ -0,0 +1,659 @@
+---
+name: ui-ux-pro-max
+description: "UI/UX design intelligence for web and mobile. Includes 50+ styles, 161 color palettes, 57 font pairings, 161 product types, 99 UX guidelines, and 25 chart types across 10 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui, and HTML/CSS). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, and check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, and mobile app. Elements: button, modal, navbar, sidebar, card, table, form, and chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, and flat design. Topics: color systems, accessibility, animation, layout, typography, font pairing, spacing, interaction states, shadow, and gradient. Integrations: shadcn/ui MCP for component search and examples."
+---
+
+# UI/UX Pro Max - Design Intelligence
+
+Comprehensive design guide for web and mobile applications. Contains 50+ styles, 161 color palettes, 57 font pairings, 161 product types with reasoning rules, 99 UX guidelines, and 25 chart types across 10 technology stacks. Searchable database with priority-based recommendations.
+
+## When to Apply
+
+This Skill should be used when the task involves **UI structure, visual design decisions, interaction patterns, or user experience quality control**.
+
+### Must Use
+
+This Skill must be invoked in the following situations:
+
+- Designing new pages (Landing Page, Dashboard, Admin, SaaS, Mobile App)
+- Creating or refactoring UI components (buttons, modals, forms, tables, charts, etc.)
+- Choosing color schemes, typography systems, spacing standards, or layout systems
+- Reviewing UI code for user experience, accessibility, or visual consistency
+- Implementing navigation structures, animations, or responsive behavior
+- Making product-level design decisions (style, information hierarchy, brand expression)
+- Improving perceived quality, clarity, or usability of interfaces
+
+### Recommended
+
+This Skill is recommended in the following situations:
+
+- UI looks "not professional enough" but the reason is unclear
+- Receiving feedback on usability or experience
+- Pre-launch UI quality optimization
+- Aligning cross-platform design (Web / iOS / Android)
+- Building design systems or reusable component libraries
+
+### Skip
+
+This Skill is not needed in the following situations:
+
+- Pure backend logic development
+- Only involving API or database design
+- Performance optimization unrelated to the interface
+- Infrastructure or DevOps work
+- Non-visual scripts or automation tasks
+
+**Decision criteria**: If the task will change how a feature **looks, feels, moves, or is interacted with**, this Skill should be used.
+
+## Rule Categories by Priority
+
+*For human/AI reference: follow priority 1→10 to decide which rule category to focus on first; use `--domain <Domain>` to query details when needed. Scripts do not read this table.*
+
+| Priority | Category | Impact | Domain | Key Checks (Must Have) | Anti-Patterns (Avoid) |
+|----------|----------|--------|--------|------------------------|------------------------|
+| 1 | Accessibility | CRITICAL | `ux` | Contrast 4.5:1, Alt text, Keyboard nav, Aria-labels | Removing focus rings, Icon-only buttons without labels |
+| 2 | Touch & Interaction | CRITICAL | `ux` | Min size 44×44px, 8px+ spacing, Loading feedback | Reliance on hover only, Instant state changes (0ms) |
+| 3 | Performance | HIGH | `ux` | WebP/AVIF, Lazy loading, Reserve space (CLS &lt; 0.1) | Layout thrashing, Cumulative Layout Shift |
+| 4 | Style Selection | HIGH | `style`, `product` | Match product type, Consistency, SVG icons (no emoji) | Mixing flat & skeuomorphic randomly, Emoji as icons |
+| 5 | Layout & Responsive | HIGH | `ux` | Mobile-first breakpoints, Viewport meta, No horizontal scroll | Horizontal scroll, Fixed px container widths, Disable zoom |
+| 6 | Typography & Color | MEDIUM | `typography`, `color` | Base 16px, Line-height 1.5, Semantic color tokens | Text &lt; 12px body, Gray-on-gray, Raw hex in components |
+| 7 | Animation | MEDIUM | `ux` | Duration 150–300ms, Motion conveys meaning, Spatial continuity | Decorative-only animation, Animating width/height, No reduced-motion |
+| 8 | Forms & Feedback | MEDIUM | `ux` | Visible labels, Error near field, Helper text, Progressive disclosure | Placeholder-only label, Errors only at top, Overwhelm upfront |
+| 9 | Navigation Patterns | HIGH | `ux` | Predictable back, Bottom nav ≤5, Deep linking | Overloaded nav, Broken back behavior, No deep links |
+| 10 | Charts & Data | LOW | `chart` | Legends, Tooltips, Accessible colors | Relying on color alone to convey meaning |
+
+## Quick Reference
+
+### 1. Accessibility (CRITICAL)
+
+- `color-contrast` - Minimum 4.5:1 ratio for normal text (large text 3:1); Material Design
+- `focus-states` - Visible focus rings on interactive elements (2–4px; Apple HIG, MD)
+- `alt-text` - Descriptive alt text for meaningful images
+- `aria-labels` - aria-label for icon-only buttons; accessibilityLabel in native (Apple HIG)
+- `keyboard-nav` - Tab order matches visual order; full keyboard support (Apple HIG)
+- `form-labels` - Use label with for attribute
+- `skip-links` - Skip to main content for keyboard users
+- `heading-hierarchy` - Sequential h1→h6, no level skip
+- `color-not-only` - Don't convey info by color alone (add icon/text)
+- `dynamic-type` - Support system text scaling; avoid truncation as text grows (Apple Dynamic Type, MD)
+- `reduced-motion` - Respect prefers-reduced-motion; reduce/disable animations when requested (Apple Reduced Motion API, MD)
+- `voiceover-sr` - Meaningful accessibilityLabel/accessibilityHint; logical reading order for VoiceOver/screen readers (Apple HIG, MD)
+- `escape-routes` - Provide cancel/back in modals and multi-step flows (Apple HIG)
+- `keyboard-shortcuts` - Preserve system and a11y shortcuts; offer keyboard alternatives for drag-and-drop (Apple HIG)
+
+### 2. Touch & Interaction (CRITICAL)
+
+- `touch-target-size` - Min 44×44pt (Apple) / 48×48dp (Material); extend hit area beyond visual bounds if needed
+- `touch-spacing` - Minimum 8px/8dp gap between touch targets (Apple HIG, MD)
+- `hover-vs-tap` - Use click/tap for primary interactions; don't rely on hover alone
+- `loading-buttons` - Disable button during async operations; show spinner or progress
+- `error-feedback` - Clear error messages near problem
+- `cursor-pointer` - Add cursor-pointer to clickable elements (Web)
+- `gesture-conflicts` - Avoid horizontal swipe on main content; prefer vertical scroll
+- `tap-delay` - Use touch-action: manipulation to reduce 300ms delay (Web)
+- `standard-gestures` - Use platform standard gestures consistently; don't redefine (e.g. swipe-back, pinch-zoom) (Apple HIG)
+- `system-gestures` - Don't block system gestures (Control Center, back swipe, etc.) (Apple HIG)
+- `press-feedback` - Visual feedback on press (ripple/highlight; MD state layers)
+- `haptic-feedback` - Use haptic for confirmations and important actions; avoid overuse (Apple HIG)
+- `gesture-alternative` - Don't rely on gesture-only interactions; always provide visible controls for critical actions
+- `safe-area-awareness` - Keep primary touch targets away from notch, Dynamic Island, gesture bar and screen edges
+- `no-precision-required` - Avoid requiring pixel-perfect taps on small icons or thin edges
+- `swipe-clarity` - Swipe actions must show clear affordance or hint (chevron, label, tutorial)
+- `drag-threshold` - Use a movement threshold before starting drag to avoid accidental drags
+
+### 3. Performance (HIGH)
+
+- `image-optimization` - Use WebP/AVIF, responsive images (srcset/sizes), lazy load non-critical assets
+- `image-dimension` - Declare width/height or use aspect-ratio to prevent layout shift (Core Web Vitals: CLS)
+- `font-loading` - Use font-display: swap/optional to avoid invisible text (FOIT); reserve space to reduce layout shift (MD)
+- `font-preload` - Preload only critical fonts; avoid overusing preload on every variant
+- `critical-css` - Prioritize above-the-fold CSS (inline critical CSS or early-loaded stylesheet)
+- `lazy-loading` - Lazy load non-hero components via dynamic import / route-level splitting
+- `bundle-splitting` - Split code by route/feature (React Suspense / Next.js dynamic) to reduce initial load and TTI
+- `third-party-scripts` - Load third-party scripts async/defer; audit and remove unnecessary ones (MD)
+- `reduce-reflows` - Avoid frequent layout reads/writes; batch DOM reads then writes
+- `content-jumping` - Reserve space for async content to avoid layout jumps (Core Web Vitals: CLS)
+- `lazy-load-below-fold` - Use loading="lazy" for below-the-fold images and heavy media
+- `virtualize-lists` - Virtualize lists with 50+ items to improve memory efficiency and scroll performance
+- `main-thread-budget` - Keep per-frame work under ~16ms for 60fps; move heavy tasks off main thread (HIG, MD)
+- `progressive-loading` - Use skeleton screens / shimmer instead of long blocking spinners for >1s operations (Apple HIG)
+- `input-latency` - Keep input latency under ~100ms for taps/scrolls (Material responsiveness standard)
+- `tap-feedback-speed` - Provide visual feedback within 100ms of tap (Apple HIG)
+- `debounce-throttle` - Use debounce/throttle for high-frequency events (scroll, resize, input)
+- `offline-support` - Provide offline state messaging and basic fallback (PWA / mobile)
+- `network-fallback` - Offer degraded modes for slow networks (lower-res images, fewer animations)
+
+### 4. Style Selection (HIGH)
+
+- `style-match` - Match style to product type (use `--design-system` for recommendations)
+- `consistency` - Use same style across all pages
+- `no-emoji-icons` - Use SVG icons (Heroicons, Lucide), not emojis
+- `color-palette-from-product` - Choose palette from product/industry (search `--domain color`)
+- `effects-match-style` - Shadows, blur, radius aligned with chosen style (glass / flat / clay etc.)
+- `platform-adaptive` - Respect platform idioms (iOS HIG vs Material): navigation, controls, typography, motion
+- `state-clarity` - Make hover/pressed/disabled states visually distinct while staying on-style (Material state layers)
+- `elevation-consistent` - Use a consistent elevation/shadow scale for cards, sheets, modals; avoid random shadow values
+- `dark-mode-pairing` - Design light/dark variants together to keep brand, contrast, and style consistent
+- `icon-style-consistent` - Use one icon set/visual language (stroke width, corner radius) across the product
+- `system-controls` - Prefer native/system controls over fully custom ones; only customize when branding requires it (Apple HIG)
+- `blur-purpose` - Use blur to indicate background dismissal (modals, sheets), not as decoration (Apple HIG)
+- `primary-action` - Each screen should have only one primary CTA; secondary actions visually subordinate (Apple HIG)
+
+### 5. Layout & Responsive (HIGH)
+
+- `viewport-meta` - width=device-width initial-scale=1 (never disable zoom)
+- `mobile-first` - Design mobile-first, then scale up to tablet and desktop
+- `breakpoint-consistency` - Use systematic breakpoints (e.g. 375 / 768 / 1024 / 1440)
+- `readable-font-size` - Minimum 16px body text on mobile (avoids iOS auto-zoom)
+- `line-length-control` - Mobile 35–60 chars per line; desktop 60–75 chars
+- `horizontal-scroll` - No horizontal scroll on mobile; ensure content fits viewport width
+- `spacing-scale` - Use 4pt/8dp incremental spacing system (Material Design)
+- `touch-density` - Keep component spacing comfortable for touch: not cramped, not causing mis-taps
+- `container-width` - Consistent max-width on desktop (max-w-6xl / 7xl)
+- `z-index-management` - Define layered z-index scale (e.g. 0 / 10 / 20 / 40 / 100 / 1000)
+- `fixed-element-offset` - Fixed navbar/bottom bar must reserve safe padding for underlying content
+- `scroll-behavior` - Avoid nested scroll regions that interfere with the main scroll experience
+- `viewport-units` - Prefer min-h-dvh over 100vh on mobile
+- `orientation-support` - Keep layout readable and operable in landscape mode
+- `content-priority` - Show core content first on mobile; fold or hide secondary content
+- `visual-hierarchy` - Establish hierarchy via size, spacing, contrast — not color alone
+
+### 6. Typography & Color (MEDIUM)
+
+- `line-height` - Use 1.5-1.75 for body text
+- `line-length` - Limit to 65-75 characters per line
+- `font-pairing` - Match heading/body font personalities
+- `font-scale` - Consistent type scale (e.g. 12 14 16 18 24 32)
+- `contrast-readability` - Darker text on light backgrounds (e.g. slate-900 on white)
+- `text-styles-system` - Use platform type system: iOS 11 Dynamic Type styles / Material 5 type roles (display, headline, title, body, label) (HIG, MD)
+- `weight-hierarchy` - Use font-weight to reinforce hierarchy: Bold headings (600–700), Regular body (400), Medium labels (500) (MD)
+- `color-semantic` - Define semantic color tokens (primary, secondary, error, surface, on-surface) not raw hex in components (Material color system)
+- `color-dark-mode` - Dark mode uses desaturated / lighter tonal variants, not inverted colors; test contrast separately (HIG, MD)
+- `color-accessible-pairs` - Foreground/background pairs must meet 4.5:1 (AA) or 7:1 (AAA); use tools to verify (WCAG, MD)
+- `color-not-decorative-only` - Functional color (error red, success green) must include icon/text; avoid color-only meaning (HIG, MD)
+- `truncation-strategy` - Prefer wrapping over truncation; when truncating use ellipsis and provide full text via tooltip/expand (Apple HIG)
+- `letter-spacing` - Respect default letter-spacing per platform; avoid tight tracking on body text (HIG, MD)
+- `number-tabular` - Use tabular/monospaced figures for data columns, prices, and timers to prevent layout shift
+- `whitespace-balance` - Use whitespace intentionally to group related items and separate sections; avoid visual clutter (Apple HIG)
+
+### 7. Animation (MEDIUM)
+
+- `duration-timing` - Use 150–300ms for micro-interactions; complex transitions ≤400ms; avoid >500ms (MD)
+- `transform-performance` - Use transform/opacity only; avoid animating width/height/top/left
+- `loading-states` - Show skeleton or progress indicator when loading exceeds 300ms
+- `excessive-motion` - Animate 1-2 key elements per view max
+- `easing` - Use ease-out for entering, ease-in for exiting; avoid linear for UI transitions
+- `motion-meaning` - Every animation must express a cause-effect relationship, not just be decorative (Apple HIG)
+- `state-transition` - State changes (hover / active / expanded / collapsed / modal) should animate smoothly, not snap
+- `continuity` - Page/screen transitions should maintain spatial continuity (shared element, directional slide) (Apple HIG)
+- `parallax-subtle` - Use parallax sparingly; must respect reduced-motion and not cause disorientation (Apple HIG)
+- `spring-physics` - Prefer spring/physics-based curves over linear or cubic-bezier for natural feel (Apple HIG fluid animations)
+- `exit-faster-than-enter` - Exit animations shorter than enter (~60–70% of enter duration) to feel responsive (MD motion)
+- `stagger-sequence` - Stagger list/grid item entrance by 30–50ms per item; avoid all-at-once or too-slow reveals (MD)
+- `shared-element-transition` - Use shared element / hero transitions for visual continuity between screens (MD, HIG)
+- `interruptible` - Animations must be interruptible; user tap/gesture cancels in-progress animation immediately (Apple HIG)
+- `no-blocking-animation` - Never block user input during an animation; UI must stay interactive (Apple HIG)
+- `fade-crossfade` - Use crossfade for content replacement within the same container (MD)
+- `scale-feedback` - Subtle scale (0.95–1.05) on press for tappable cards/buttons; restore on release (HIG, MD)
+- `gesture-feedback` - Drag, swipe, and pinch must provide real-time visual response tracking the finger (MD Motion)
+- `hierarchy-motion` - Use translate/scale direction to express hierarchy: enter from below = deeper, exit upward = back (MD)
+- `motion-consistency` - Unify duration/easing tokens globally; all animations share the same rhythm and feel
+- `opacity-threshold` - Fading elements should not linger below opacity 0.2; either fade fully or remain visible
+- `modal-motion` - Modals/sheets should animate from their trigger source (scale+fade or slide-in) for spatial context (HIG, MD)
+- `navigation-direction` - Forward navigation animates left/up; backward animates right/down — keep direction logically consistent (HIG)
+- `layout-shift-avoid` - Animations must not cause layout reflow or CLS; use transform for position changes
+
+### 8. Forms & Feedback (MEDIUM)
+
+- `input-labels` - Visible label per input (not placeholder-only)
+- `error-placement` - Show error below the related field
+- `submit-feedback` - Loading then success/error state on submit
+- `required-indicators` - Mark required fields (e.g. asterisk)
+- `empty-states` - Helpful message and action when no content
+- `toast-dismiss` - Auto-dismiss toasts in 3-5s
+- `confirmation-dialogs` - Confirm before destructive actions
+- `input-helper-text` - Provide persistent helper text below complex inputs, not just placeholder (Material Design)
+- `disabled-states` - Disabled elements use reduced opacity (0.38–0.5) + cursor change + semantic attribute (MD)
+- `progressive-disclosure` - Reveal complex options progressively; don't overwhelm users upfront (Apple HIG)
+- `inline-validation` - Validate on blur (not keystroke); show error only after user finishes input (MD)
+- `input-type-keyboard` - Use semantic input types (email, tel, number) to trigger the correct mobile keyboard (HIG, MD)
+- `password-toggle` - Provide show/hide toggle for password fields (MD)
+- `autofill-support` - Use autocomplete / textContentType attributes so the system can autofill (HIG, MD)
+- `undo-support` - Allow undo for destructive or bulk actions (e.g. "Undo delete" toast) (Apple HIG)
+- `success-feedback` - Confirm completed actions with brief visual feedback (checkmark, toast, color flash) (MD)
+- `error-recovery` - Error messages must include a clear recovery path (retry, edit, help link) (HIG, MD)
+- `multi-step-progress` - Multi-step flows show step indicator or progress bar; allow back navigation (MD)
+- `form-autosave` - Long forms should auto-save drafts to prevent data loss on accidental dismissal (Apple HIG)
+- `sheet-dismiss-confirm` - Confirm before dismissing a sheet/modal with unsaved changes (Apple HIG)
+- `error-clarity` - Error messages must state cause + how to fix (not just "Invalid input") (HIG, MD)
+- `field-grouping` - Group related fields logically (fieldset/legend or visual grouping) (MD)
+- `read-only-distinction` - Read-only state should be visually and semantically different from disabled (MD)
+- `focus-management` - After submit error, auto-focus the first invalid field (WCAG, MD)
+- `error-summary` - For multiple errors, show summary at top with anchor links to each field (WCAG)
+- `touch-friendly-input` - Mobile input height ≥44px to meet touch target requirements (Apple HIG)
+- `destructive-emphasis` - Destructive actions use semantic danger color (red) and are visually separated from primary actions (HIG, MD)
+- `toast-accessibility` - Toasts must not steal focus; use aria-live="polite" for screen reader announcement (WCAG)
+- `aria-live-errors` - Form errors use aria-live region or role="alert" to notify screen readers (WCAG)
+- `contrast-feedback` - Error and success state colors must meet 4.5:1 contrast ratio (WCAG, MD)
+- `timeout-feedback` - Request timeout must show clear feedback with retry option (MD)
+
+### 9. Navigation Patterns (HIGH)
+
+- `bottom-nav-limit` - Bottom navigation max 5 items; use labels with icons (Material Design)
+- `drawer-usage` - Use drawer/sidebar for secondary navigation, not primary actions (Material Design)
+- `back-behavior` - Back navigation must be predictable and consistent; preserve scroll/state (Apple HIG, MD)
+- `deep-linking` - All key screens must be reachable via deep link / URL for sharing and notifications (Apple HIG, MD)
+- `tab-bar-ios` - iOS: use bottom Tab Bar for top-level navigation (Apple HIG)
+- `top-app-bar-android` - Android: use Top App Bar with navigation icon for primary structure (Material Design)
+- `nav-label-icon` - Navigation items must have both icon and text label; icon-only nav harms discoverability (MD)
+- `nav-state-active` - Current location must be visually highlighted (color, weight, indicator) in navigation (HIG, MD)
+- `nav-hierarchy` - Primary nav (tabs/bottom bar) vs secondary nav (drawer/settings) must be clearly separated (MD)
+- `modal-escape` - Modals and sheets must offer a clear close/dismiss affordance; swipe-down to dismiss on mobile (Apple HIG)
+- `search-accessible` - Search must be easily reachable (top bar or tab); provide recent/suggested queries (MD)
+- `breadcrumb-web` - Web: use breadcrumbs for 3+ level deep hierarchies to aid orientation (MD)
+- `state-preservation` - Navigating back must restore previous scroll position, filter state, and input (HIG, MD)
+- `gesture-nav-support` - Support system gesture navigation (iOS swipe-back, Android predictive back) without conflict (HIG, MD)
+- `tab-badge` - Use badges on nav items sparingly to indicate unread/pending; clear after user visits (HIG, MD)
+- `overflow-menu` - When actions exceed available space, use overflow/more menu instead of cramming (MD)
+- `bottom-nav-top-level` - Bottom nav is for top-level screens only; never nest sub-navigation inside it (MD)
+- `adaptive-navigation` - Large screens (≥1024px) prefer sidebar; small screens use bottom/top nav (Material Adaptive)
+- `back-stack-integrity` - Never silently reset the navigation stack or unexpectedly jump to home (HIG, MD)
+- `navigation-consistency` - Navigation placement must stay the same across all pages; don't change by page type
+- `avoid-mixed-patterns` - Don't mix Tab + Sidebar + Bottom Nav at the same hierarchy level
+- `modal-vs-navigation` - Modals must not be used for primary navigation flows; they break the user's path (HIG)
+- `focus-on-route-change` - After page transition, move focus to main content region for screen reader users (WCAG)
+- `persistent-nav` - Core navigation must remain reachable from deep pages; don't hide it entirely in sub-flows (HIG, MD)
+- `destructive-nav-separation` - Dangerous actions (delete account, logout) must be visually and spatially separated from normal nav items (HIG, MD)
+- `empty-nav-state` - When a nav destination is unavailable, explain why instead of silently hiding it (MD)
+
+### 10. Charts & Data (LOW)
+
+- `chart-type` - Match chart type to data type (trend → line, comparison → bar, proportion → pie/donut)
+- `color-guidance` - Use accessible color palettes; avoid red/green only pairs for colorblind users (WCAG, MD)
+- `data-table` - Provide table alternative for accessibility; charts alone are not screen-reader friendly (WCAG)
+- `pattern-texture` - Supplement color with patterns, textures, or shapes so data is distinguishable without color (WCAG, MD)
+- `legend-visible` - Always show legend; position near the chart, not detached below a scroll fold (MD)
+- `tooltip-on-interact` - Provide tooltips/data labels on hover (Web) or tap (mobile) showing exact values (HIG, MD)
+- `axis-labels` - Label axes with units and readable scale; avoid truncated or rotated labels on mobile
+- `responsive-chart` - Charts must reflow or simplify on small screens (e.g. horizontal bar instead of vertical, fewer ticks)
+- `empty-data-state` - Show meaningful empty state when no data exists ("No data yet" + guidance), not a blank chart (MD)
+- `loading-chart` - Use skeleton or shimmer placeholder while chart data loads; don't show an empty axis frame
+- `animation-optional` - Chart entrance animations must respect prefers-reduced-motion; data should be readable immediately (HIG)
+- `large-dataset` - For 1000+ data points, aggregate or sample; provide drill-down for detail instead of rendering all (MD)
+- `number-formatting` - Use locale-aware formatting for numbers, dates, currencies on axes and labels (HIG, MD)
+- `touch-target-chart` - Interactive chart elements (points, segments) must have ≥44pt tap area or expand on touch (Apple HIG)
+- `no-pie-overuse` - Avoid pie/donut for >5 categories; switch to bar chart for clarity
+- `contrast-data` - Data lines/bars vs background ≥3:1; data text labels ≥4.5:1 (WCAG)
+- `legend-interactive` - Legends should be clickable to toggle series visibility (MD)
+- `direct-labeling` - For small datasets, label values directly on the chart to reduce eye travel
+- `tooltip-keyboard` - Tooltip content must be keyboard-reachable and not rely on hover alone (WCAG)
+- `sortable-table` - Data tables must support sorting with aria-sort indicating current sort state (WCAG)
+- `axis-readability` - Axis ticks must not be cramped; maintain readable spacing, auto-skip on small screens
+- `data-density` - Limit information density per chart to avoid cognitive overload; split into multiple charts if needed
+- `trend-emphasis` - Emphasize data trends over decoration; avoid heavy gradients/shadows that obscure the data
+- `gridline-subtle` - Grid lines should be low-contrast (e.g. gray-200) so they don't compete with data
+- `focusable-elements` - Interactive chart elements (points, bars, slices) must be keyboard-navigable (WCAG)
+- `screen-reader-summary` - Provide a text summary or aria-label describing the chart's key insight for screen readers (WCAG)
+- `error-state-chart` - Data load failure must show error message with retry action, not a broken/empty chart
+- `export-option` - For data-heavy products, offer CSV/image export of chart data
+- `drill-down-consistency` - Drill-down interactions must maintain a clear back-path and hierarchy breadcrumb
+- `time-scale-clarity` - Time series charts must clearly label time granularity (day/week/month) and allow switching
+
+## How to Use
+
+Search specific domains using the CLI tool below.
+
+---
+
+## Prerequisites
+
+Check if Python is installed:
+
+```bash
+python3 --version || python --version
+```
+
+If Python is not installed, install it based on user's OS:
+
+**macOS:**
+```bash
+brew install python3
+```
+
+**Ubuntu/Debian:**
+```bash
+sudo apt update && sudo apt install python3
+```
+
+**Windows:**
+```powershell
+winget install Python.Python.3.12
+```
+
+---
+
+## How to Use This Skill
+
+Use this skill when the user requests any of the following:
+
+| Scenario | Trigger Examples | Start From |
+|----------|-----------------|------------|
+| **New project / page** | "Build a landing page", "Build a dashboard" | Step 1 → Step 2 (design system) |
+| **New component** | "Create a pricing card", "Add a modal" | Step 3 (domain search: style, ux) |
+| **Choose style / color / font** | "What style fits a fintech app?", "Recommend a color palette" | Step 2 (design system) |
+| **Review existing UI** | "Review this page for UX issues", "Check accessibility" | Quick Reference checklist above |
+| **Fix a UI bug** | "Button hover is broken", "Layout shifts on load" | Quick Reference → relevant section |
+| **Improve / optimize** | "Make this faster", "Improve mobile experience" | Step 3 (domain search: ux, react) |
+| **Implement dark mode** | "Add dark mode support" | Step 3 (domain: style "dark mode") |
+| **Add charts / data viz** | "Add an analytics dashboard chart" | Step 3 (domain: chart) |
+| **Stack best practices** | "React performance tips"、"SwiftUI navigation" | Step 4 (stack search) |
+
+Follow this workflow:
+
+### Step 1: Analyze User Requirements
+
+Extract key information from user request:
+- **Product type**: Entertainment (social, video, music, gaming), Tool (scanner, editor, converter), Productivity (task manager, notes, calendar), or hybrid
+- **Target audience**: C-end consumer users; consider age group, usage context (commute, leisure, work)
+- **Style keywords**: playful, vibrant, minimal, dark mode, content-first, immersive, etc.
+- **Stack**: React Native (this project's only tech stack)
+
+### Step 2: Generate Design System (REQUIRED)
+
+**Always start with `--design-system`** to get comprehensive recommendations with reasoning:
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "<product_type> <industry> <keywords>" --design-system [-p "Project Name"]
+```
+
+This command:
+1. Searches domains in parallel (product, style, color, landing, typography)
+2. Applies reasoning rules from `ui-reasoning.csv` to select best matches
+3. Returns complete design system: pattern, style, colors, typography, effects
+4. Includes anti-patterns to avoid
+
+**Example:**
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "beauty spa wellness service" --design-system -p "Serenity Spa"
+```
+
+### Step 2b: Persist Design System (Master + Overrides Pattern)
+
+To save the design system for **hierarchical retrieval across sessions**, add `--persist`:
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Project Name"
+```
+
+This creates:
+- `design-system/MASTER.md` — Global Source of Truth with all design rules
+- `design-system/pages/` — Folder for page-specific overrides
+
+**With page-specific override:**
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Project Name" --page "dashboard"
+```
+
+This also creates:
+- `design-system/pages/dashboard.md` — Page-specific deviations from Master
+
+**How hierarchical retrieval works:**
+1. When building a specific page (e.g., "Checkout"), first check `design-system/pages/checkout.md`
+2. If the page file exists, its rules **override** the Master file
+3. If not, use `design-system/MASTER.md` exclusively
+
+**Context-aware retrieval prompt:**
+```
+I am building the [Page Name] page. Please read design-system/MASTER.md.
+Also check if design-system/pages/[page-name].md exists.
+If the page file exists, prioritize its rules.
+If not, use the Master rules exclusively.
+Now, generate the code...
+```
+
+### Step 3: Supplement with Detailed Searches (as needed)
+
+After getting the design system, use domain searches to get additional details:
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "<keyword>" --domain <domain> [-n <max_results>]
+```
+
+**When to use detailed searches:**
+
+| Need | Domain | Example |
+|------|--------|---------|
+| Product type patterns | `product` | `--domain product "entertainment social"` |
+| More style options | `style` | `--domain style "glassmorphism dark"` |
+| Color palettes | `color` | `--domain color "entertainment vibrant"` |
+| Font pairings | `typography` | `--domain typography "playful modern"` |
+| Chart recommendations | `chart` | `--domain chart "real-time dashboard"` |
+| UX best practices | `ux` | `--domain ux "animation accessibility"` |
+| Alternative fonts | `typography` | `--domain typography "elegant luxury"` |
+| Individual Google Fonts | `google-fonts` | `--domain google-fonts "sans serif popular variable"` |
+| Landing structure | `landing` | `--domain landing "hero social-proof"` |
+| React Native perf | `react` | `--domain react "rerender memo list"` |
+| App interface a11y | `web` | `--domain web "accessibilityLabel touch safe-areas"` |
+| AI prompt / CSS keywords | `prompt` | `--domain prompt "minimalism"` |
+
+### Step 4: Stack Guidelines (React Native)
+
+Get React Native implementation-specific best practices:
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "<keyword>" --stack react-native
+```
+
+---
+
+## Search Reference
+
+### Available Domains
+
+| Domain | Use For | Example Keywords |
+|--------|---------|------------------|
+| `product` | Product type recommendations | SaaS, e-commerce, portfolio, healthcare, beauty, service |
+| `style` | UI styles, colors, effects | glassmorphism, minimalism, dark mode, brutalism |
+| `typography` | Font pairings, Google Fonts | elegant, playful, professional, modern |
+| `color` | Color palettes by product type | saas, ecommerce, healthcare, beauty, fintech, service |
+| `landing` | Page structure, CTA strategies | hero, hero-centric, testimonial, pricing, social-proof |
+| `chart` | Chart types, library recommendations | trend, comparison, timeline, funnel, pie |
+| `ux` | Best practices, anti-patterns | animation, accessibility, z-index, loading |
+| `google-fonts` | Individual Google Fonts lookup | sans serif, monospace, japanese, variable font, popular |
+| `react` | React/Next.js performance | waterfall, bundle, suspense, memo, rerender, cache |
+| `web` | App interface guidelines (iOS/Android/React Native) | accessibilityLabel, touch targets, safe areas, Dynamic Type |
+| `prompt` | AI prompts, CSS keywords | (style name) |
+
+### Available Stacks
+
+| Stack | Focus |
+|-------|-------|
+| `react-native` | Components, Navigation, Lists |
+
+---
+
+## Example Workflow
+
+**User request:** "Make an AI search homepage."
+
+### Step 1: Analyze Requirements
+- Product type: Tool (AI search engine)
+- Target audience: C-end users looking for fast, intelligent search
+- Style keywords: modern, minimal, content-first, dark mode
+- Stack: React Native
+
+### Step 2: Generate Design System (REQUIRED)
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "AI search tool modern minimal" --design-system -p "AI Search"
+```
+
+**Output:** Complete design system with pattern, style, colors, typography, effects, and anti-patterns.
+
+### Step 3: Supplement with Detailed Searches (as needed)
+
+```bash
+# Get style options for a modern tool product
+python3 skills/ui-ux-pro-max/scripts/search.py "minimalism dark mode" --domain style
+
+# Get UX best practices for search interaction and loading
+python3 skills/ui-ux-pro-max/scripts/search.py "search loading animation" --domain ux
+```
+
+### Step 4: Stack Guidelines
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "list performance navigation" --stack react-native
+```
+
+**Then:** Synthesize design system + detailed searches and implement the design.
+
+---
+
+## Output Formats
+
+The `--design-system` flag supports two output formats:
+
+```bash
+# ASCII box (default) - best for terminal display
+python3 skills/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system
+
+# Markdown - best for documentation
+python3 skills/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system -f markdown
+```
+
+---
+
+## Tips for Better Results
+
+### Query Strategy
+
+- Use **multi-dimensional keywords** — combine product + industry + tone + density: `"entertainment social vibrant content-dense"` not just `"app"`
+- Try different keywords for the same need: `"playful neon"` → `"vibrant dark"` → `"content-first minimal"`
+- Use `--design-system` first for full recommendations, then `--domain` to deep-dive any dimension you're unsure about
+- Always add `--stack react-native` for implementation-specific guidance
+
+### Common Sticking Points
+
+| Problem | What to Do |
+|---------|------------|
+| Can't decide on style/color | Re-run `--design-system` with different keywords |
+| Dark mode contrast issues | Quick Reference §6: `color-dark-mode` + `color-accessible-pairs` |
+| Animations feel unnatural | Quick Reference §7: `spring-physics` + `easing` + `exit-faster-than-enter` |
+| Form UX is poor | Quick Reference §8: `inline-validation` + `error-clarity` + `focus-management` |
+| Navigation feels confusing | Quick Reference §9: `nav-hierarchy` + `bottom-nav-limit` + `back-behavior` |
+| Layout breaks on small screens | Quick Reference §5: `mobile-first` + `breakpoint-consistency` |
+| Performance / jank | Quick Reference §3: `virtualize-lists` + `main-thread-budget` + `debounce-throttle` |
+
+### Pre-Delivery Checklist
+
+- Run `--domain ux "animation accessibility z-index loading"` as a UX validation pass before implementation
+- Run through Quick Reference **§1–§3** (CRITICAL + HIGH) as a final review
+- Test on 375px (small phone) and landscape orientation
+- Verify behavior with **reduced-motion** enabled and **Dynamic Type** at largest size
+- Check dark mode contrast independently (don't assume light mode values work)
+- Confirm all touch targets ≥44pt and no content hidden behind safe areas
+
+---
+
+## Common Rules for Professional UI
+
+These are frequently overlooked issues that make UI look unprofessional:
+Scope notice: The rules below are for App UI (iOS/Android/React Native/Flutter), not desktop-web interaction patterns.
+
+### Icons & Visual Elements
+
+| Rule | Standard | Avoid | Why It Matters |
+|------|----------|--------|----------------|
+| **No Emoji as Structural Icons** | Use vector-based icons (e.g., Lucide, react-native-vector-icons, @expo/vector-icons). | Using emojis (🎨 🚀 ⚙️) for navigation, settings, or system controls. | Emojis are font-dependent, inconsistent across platforms, and cannot be controlled via design tokens. |
+| **Vector-Only Assets** | Use SVG or platform vector icons that scale cleanly and support theming. | Raster PNG icons that blur or pixelate. | Ensures scalability, crisp rendering, and dark/light mode adaptability. |
+| **Stable Interaction States** | Use color, opacity, or elevation transitions for press states without changing layout bounds. | Layout-shifting transforms that move surrounding content or trigger visual jitter. | Prevents unstable interactions and preserves smooth motion/perceived quality on mobile. |
+| **Correct Brand Logos** | Use official brand assets and follow their usage guidelines (spacing, color, clear space). | Guessing logo paths, recoloring unofficially, or modifying proportions. | Prevents brand misuse and ensures legal/platform compliance. |
+| **Consistent Icon Sizing** | Define icon sizes as design tokens (e.g., icon-sm, icon-md = 24pt, icon-lg). | Mixing arbitrary values like 20pt / 24pt / 28pt randomly. | Maintains rhythm and visual hierarchy across the interface. |
+| **Stroke Consistency** | Use a consistent stroke width within the same visual layer (e.g., 1.5px or 2px). | Mixing thick and thin stroke styles arbitrarily. | Inconsistent strokes reduce perceived polish and cohesion. |
+| **Filled vs Outline Discipline** | Use one icon style per hierarchy level. | Mixing filled and outline icons at the same hierarchy level. | Maintains semantic clarity and stylistic coherence. |
+| **Touch Target Minimum** | Minimum 44×44pt interactive area (use hitSlop if icon is smaller). | Small icons without expanded tap area. | Meets accessibility and platform usability standards. |
+| **Icon Alignment** | Align icons to text baseline and maintain consistent padding. | Misaligned icons or inconsistent spacing around them. | Prevents subtle visual imbalance that reduces perceived quality. |
+| **Icon Contrast** | Follow WCAG contrast standards: 4.5:1 for small elements, 3:1 minimum for larger UI glyphs. | Low-contrast icons that blend into the background. | Ensures accessibility in both light and dark modes. |
+
+
+### Interaction (App)
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **Tap feedback** | Provide clear pressed feedback (ripple/opacity/elevation) within 80-150ms | No visual response on tap |
+| **Animation timing** | Keep micro-interactions around 150-300ms with platform-native easing | Instant transitions or slow animations (>500ms) |
+| **Accessibility focus** | Ensure screen reader focus order matches visual order and labels are descriptive | Unlabeled controls or confusing focus traversal |
+| **Disabled state clarity** | Use disabled semantics (`disabled`/native disabled props), reduced emphasis, and no tap action | Controls that look tappable but do nothing |
+| **Touch target minimum** | Keep tap areas >=44x44pt (iOS) or >=48x48dp (Android), expand hit area when icon is smaller | Tiny tap targets or icon-only hit areas without padding |
+| **Gesture conflict prevention** | Keep one primary gesture per region and avoid nested tap/drag conflicts | Overlapping gestures causing accidental actions |
+| **Semantic native controls** | Prefer native interactive primitives (`Button`, `Pressable`, platform equivalents) with proper accessibility roles | Generic containers used as primary controls without semantics |
+
+### Light/Dark Mode Contrast
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **Surface readability (light)** | Keep cards/surfaces clearly separated from background with sufficient opacity/elevation | Overly transparent surfaces that blur hierarchy |
+| **Text contrast (light)** | Maintain body text contrast >=4.5:1 against light surfaces | Low-contrast gray body text |
+| **Text contrast (dark)** | Maintain primary text contrast >=4.5:1 and secondary text >=3:1 on dark surfaces | Dark mode text that blends into background |
+| **Border and divider visibility** | Ensure separators are visible in both themes (not just light mode) | Theme-specific borders disappearing in one mode |
+| **State contrast parity** | Keep pressed/focused/disabled states equally distinguishable in light and dark themes | Defining interaction states for one theme only |
+| **Token-driven theming** | Use semantic color tokens mapped per theme across app surfaces/text/icons | Hardcoded per-screen hex values |
+| **Scrim and modal legibility** | Use a modal scrim strong enough to isolate foreground content (typically 40-60% black) | Weak scrim that leaves background visually competing |
+
+### Layout & Spacing
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **Safe-area compliance** | Respect top/bottom safe areas for all fixed headers, tab bars, and CTA bars | Placing fixed UI under notch, status bar, or gesture area |
+| **System bar clearance** | Add spacing for status/navigation bars and gesture home indicator | Let tappable content collide with OS chrome |
+| **Consistent content width** | Keep predictable content width per device class (phone/tablet) | Mixing arbitrary widths between screens |
+| **8dp spacing rhythm** | Use a consistent 4/8dp spacing system for padding/gaps/section spacing | Random spacing increments with no rhythm |
+| **Readable text measure** | Keep long-form text readable on large devices (avoid edge-to-edge paragraphs on tablets) | Full-width long text that hurts readability |
+| **Section spacing hierarchy** | Define clear vertical rhythm tiers (e.g., 16/24/32/48) by hierarchy | Similar UI levels with inconsistent spacing |
+| **Adaptive gutters by breakpoint** | Increase horizontal insets on larger widths and in landscape | Same narrow gutter on all device sizes/orientations |
+| **Scroll and fixed element coexistence** | Add bottom/top content insets so lists are not hidden behind fixed bars | Scroll content obscured by sticky headers/footers |
+
+---
+
+## Pre-Delivery Checklist
+
+Before delivering UI code, verify these items:
+Scope notice: This checklist is for App UI (iOS/Android/React Native/Flutter).
+
+### Visual Quality
+- [ ] No emojis used as icons (use SVG instead)
+- [ ] All icons come from a consistent icon family and style
+- [ ] Official brand assets are used with correct proportions and clear space
+- [ ] Pressed-state visuals do not shift layout bounds or cause jitter
+- [ ] Semantic theme tokens are used consistently (no ad-hoc per-screen hardcoded colors)
+
+### Interaction
+- [ ] All tappable elements provide clear pressed feedback (ripple/opacity/elevation)
+- [ ] Touch targets meet minimum size (>=44x44pt iOS, >=48x48dp Android)
+- [ ] Micro-interaction timing stays in the 150-300ms range with native-feeling easing
+- [ ] Disabled states are visually clear and non-interactive
+- [ ] Screen reader focus order matches visual order, and interactive labels are descriptive
+- [ ] Gesture regions avoid nested/conflicting interactions (tap/drag/back-swipe conflicts)
+
+### Light/Dark Mode
+- [ ] Primary text contrast >=4.5:1 in both light and dark mode
+- [ ] Secondary text contrast >=3:1 in both light and dark mode
+- [ ] Dividers/borders and interaction states are distinguishable in both modes
+- [ ] Modal/drawer scrim opacity is strong enough to preserve foreground legibility (typically 40-60% black)
+- [ ] Both themes are tested before delivery (not inferred from a single theme)
+
+### Layout
+- [ ] Safe areas are respected for headers, tab bars, and bottom CTA bars
+- [ ] Scroll content is not hidden behind fixed/sticky bars
+- [ ] Verified on small phone, large phone, and tablet (portrait + landscape)
+- [ ] Horizontal insets/gutters adapt correctly by device size and orientation
+- [ ] 4/8dp spacing rhythm is maintained across component, section, and page levels
+- [ ] Long-form text measure remains readable on larger devices (no edge-to-edge paragraphs)
+
+### Accessibility
+- [ ] All meaningful images/icons have accessibility labels
+- [ ] Form fields have labels, hints, and clear error messages
+- [ ] Color is not the only indicator
+- [ ] Reduced motion and dynamic text size are supported without layout breakage
+- [ ] Accessibility traits/roles/states (selected, disabled, expanded) are announced correctly

.agent/skills/ui-ux-pro-max/data

@@ -0,0 +1 @@
+../../../src/ui-ux-pro-max/data

.agent/skills/ui-ux-pro-max/scripts

@@ -0,0 +1 @@
+../../../src/ui-ux-pro-max/scripts

.agents/skills/frontend-design/LICENSE.txt

@@ -0,0 +1,177 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

.agents/skills/frontend-design/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: frontend-design
+description: "Create distinctive, production-grade frontend interfaces with intentional aesthetics, high craft, and non-generic visual identity. Use when building or styling web UIs, components, pages, dashboard..."
+risk: unknown
+source: community
+date_added: "2026-02-27"
+---
+
+# Frontend Design (Distinctive, Production-Grade)
+
+You are a **frontend designer-engineer**, not a layout generator.
+
+Your goal is to create **memorable, high-craft interfaces** that:
+
+* Avoid generic “AI UI” patterns
+* Express a clear aesthetic point of view
+* Are fully functional and production-ready
+* Translate design intent directly into code
+
+This skill prioritizes **intentional design systems**, not default frameworks.
+
+---
+
+## 1. Core Design Mandate
+
+Every output must satisfy **all four**:
+
+1. **Intentional Aesthetic Direction**
+   A named, explicit design stance (e.g. *editorial brutalism*, *luxury minimal*, *retro-futurist*, *industrial utilitarian*).
+
+2. **Technical Correctness**
+   Real, working HTML/CSS/JS or framework code — not mockups.
+
+3. **Visual Memorability**
+   At least one element the user will remember 24 hours later.
+
+4. **Cohesive Restraint**
+   No random decoration. Every flourish must serve the aesthetic thesis.
+
+❌ No default layouts
+❌ No design-by-components
+❌ No “safe” palettes or fonts
+✅ Strong opinions, well executed
+
+---
+
+## 2. Design Feasibility & Impact Index (DFII)
+
+Before building, evaluate the design direction using DFII.
+
+### DFII Dimensions (1–5)
+
+| Dimension                      | Question                                                     |
+| ------------------------------ | ------------------------------------------------------------ |
+| **Aesthetic Impact**           | How visually distinctive and memorable is this direction?    |
+| **Context Fit**                | Does this aesthetic suit the product, audience, and purpose? |
+| **Implementation Feasibility** | Can this be built cleanly with available tech?               |
+| **Performance Safety**         | Will it remain fast and accessible?                          |
+| **Consistency Risk**           | Can this be maintained across screens/components?            |
+
+### Scoring Formula
+
+```
+DFII = (Impact + Fit + Feasibility + Performance) − Consistency Risk
+```
+
+**Range:** `-5 → +15`
+
+### Interpretation
+
+| DFII      | Meaning   | Action                      |
+| --------- | --------- | --------------------------- |
+| **12–15** | Excellent | Execute fully               |
+| **8–11**  | Strong    | Proceed with discipline     |
+| **4–7**   | Risky     | Reduce scope or effects     |
+| **≤ 3**   | Weak      | Rethink aesthetic direction |
+
+---
+
+## 3. Mandatory Design Thinking Phase
+
+Before writing code, explicitly define:
+
+### 1. Purpose
+
+* What action should this interface enable?
+* Is it persuasive, functional, exploratory, or expressive?
+
+### 2. Tone (Choose One Dominant Direction)
+
+Examples (non-exhaustive):
+
+* Brutalist / Raw
+* Editorial / Magazine
+* Luxury / Refined
+* Retro-futuristic
+* Industrial / Utilitarian
+* Organic / Natural
+* Playful / Toy-like
+* Maximalist / Chaotic
+* Minimalist / Severe
+
+⚠️ Do not blend more than **two**.
+
+### 3. Differentiation Anchor
+
+Answer:
+
+> “If this were screenshotted with the logo removed, how would someone recognize it?”
+
+This anchor must be visible in the final UI.
+
+---
+
+## 4. Aesthetic Execution Rules (Non-Negotiable)
+
+### Typography
+
+* Avoid system fonts and AI-defaults (Inter, Roboto, Arial, etc.)
+* Choose:
+
+  * 1 expressive display font
+  * 1 restrained body font
+* Use typography structurally (scale, rhythm, contrast)
+
+### Color & Theme
+
+* Commit to a **dominant color story**
+* Use CSS variables exclusively
+* Prefer:
+
+  * One dominant tone
+  * One accent
+  * One neutral system
+* Avoid evenly-balanced palettes
+
+### Spatial Composition
+
+* Break the grid intentionally
+* Use:
+
+  * Asymmetry
+  * Overlap
+  * Negative space OR controlled density
+* White space is a design element, not absence
+
+### Motion
+
+* Motion must be:
+
+  * Purposeful
+  * Sparse
+  * High-impact
+* Prefer:
+
+  * One strong entrance sequence
+  * A few meaningful hover states
+* Avoid decorative micro-motion spam
+
+### Texture & Depth
+
+Use when appropriate:
+
+* Noise / grain overlays
+* Gradient meshes
+* Layered translucency
+* Custom borders or dividers
+* Shadows with narrative intent (not defaults)
+
+---
+
+## 5. Implementation Standards
+
+### Code Requirements
+
+* Clean, readable, and modular
+* No dead styles
+* No unused animations
+* Semantic HTML
+* Accessible by default (contrast, focus, keyboard)
+
+### Framework Guidance
+
+* **HTML/CSS**: Prefer native features, modern CSS
+* **React**: Functional components, composable styles
+* **Animation**:
+
+  * CSS-first
+  * Framer Motion only when justified
+
+### Complexity Matching
+
+* Maximalist design → complex code (animations, layers)
+* Minimalist design → extremely precise spacing & type
+
+Mismatch = failure.
+
+---
+
+## 6. Required Output Structure
+
+When generating frontend work:
+
+### 1. Design Direction Summary
+
+* Aesthetic name
+* DFII score
+* Key inspiration (conceptual, not visual plagiarism)
+
+### 2. Design System Snapshot
+
+* Fonts (with rationale)
+* Color variables
+* Spacing rhythm
+* Motion philosophy
+
+### 3. Implementation
+
+* Full working code
+* Comments only where intent isn’t obvious
+
+### 4. Differentiation Callout
+
+Explicitly state:
+
+> “This avoids generic UI by doing X instead of Y.”
+
+---
+
+## 7. Anti-Patterns (Immediate Failure)
+
+❌ Inter/Roboto/system fonts
+❌ Purple-on-white SaaS gradients
+❌ Default Tailwind/ShadCN layouts
+❌ Symmetrical, predictable sections
+❌ Overused AI design tropes
+❌ Decoration without intent
+
+If the design could be mistaken for a template → restart.
+
+---
+
+## 8. Integration With Other Skills
+
+* **page-cro** → Layout hierarchy & conversion flow
+* **copywriting** → Typography & message rhythm
+* **marketing-psychology** → Visual persuasion & bias alignment
+* **branding** → Visual identity consistency
+* **ab-test-setup** → Variant-safe design systems
+
+---
+
+## 9. Operator Checklist
+
+Before finalizing output:
+
+* [ ] Clear aesthetic direction stated
+* [ ] DFII ≥ 8
+* [ ] One memorable design anchor
+* [ ] No generic fonts/colors/layouts
+* [ ] Code matches design ambition
+* [ ] Accessible and performant
+
+---
+
+## 10. Questions to Ask (If Needed)
+
+1. Who is this for, emotionally?
+2. Should this feel trustworthy, exciting, calm, or provocative?
+3. Is memorability or clarity more important?
+4. Will this scale to other pages/components?
+5. What should users *feel* in the first 3 seconds?
+
+---
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

.agents/skills/ui-ux-pro-max/SKILL.md

@@ -0,0 +1,659 @@
+---
+name: ui-ux-pro-max
+description: "UI/UX design intelligence for web and mobile. Includes 50+ styles, 161 color palettes, 57 font pairings, 161 product types, 99 UX guidelines, and 25 chart types across 10 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui, and HTML/CSS). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, and check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, and mobile app. Elements: button, modal, navbar, sidebar, card, table, form, and chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, and flat design. Topics: color systems, accessibility, animation, layout, typography, font pairing, spacing, interaction states, shadow, and gradient. Integrations: shadcn/ui MCP for component search and examples."
+---
+
+# UI/UX Pro Max - Design Intelligence
+
+Comprehensive design guide for web and mobile applications. Contains 50+ styles, 161 color palettes, 57 font pairings, 161 product types with reasoning rules, 99 UX guidelines, and 25 chart types across 10 technology stacks. Searchable database with priority-based recommendations.
+
+## When to Apply
+
+This Skill should be used when the task involves **UI structure, visual design decisions, interaction patterns, or user experience quality control**.
+
+### Must Use
+
+This Skill must be invoked in the following situations:
+
+- Designing new pages (Landing Page, Dashboard, Admin, SaaS, Mobile App)
+- Creating or refactoring UI components (buttons, modals, forms, tables, charts, etc.)
+- Choosing color schemes, typography systems, spacing standards, or layout systems
+- Reviewing UI code for user experience, accessibility, or visual consistency
+- Implementing navigation structures, animations, or responsive behavior
+- Making product-level design decisions (style, information hierarchy, brand expression)
+- Improving perceived quality, clarity, or usability of interfaces
+
+### Recommended
+
+This Skill is recommended in the following situations:
+
+- UI looks "not professional enough" but the reason is unclear
+- Receiving feedback on usability or experience
+- Pre-launch UI quality optimization
+- Aligning cross-platform design (Web / iOS / Android)
+- Building design systems or reusable component libraries
+
+### Skip
+
+This Skill is not needed in the following situations:
+
+- Pure backend logic development
+- Only involving API or database design
+- Performance optimization unrelated to the interface
+- Infrastructure or DevOps work
+- Non-visual scripts or automation tasks
+
+**Decision criteria**: If the task will change how a feature **looks, feels, moves, or is interacted with**, this Skill should be used.
+
+## Rule Categories by Priority
+
+*For human/AI reference: follow priority 1→10 to decide which rule category to focus on first; use `--domain <Domain>` to query details when needed. Scripts do not read this table.*
+
+| Priority | Category | Impact | Domain | Key Checks (Must Have) | Anti-Patterns (Avoid) |
+|----------|----------|--------|--------|------------------------|------------------------|
+| 1 | Accessibility | CRITICAL | `ux` | Contrast 4.5:1, Alt text, Keyboard nav, Aria-labels | Removing focus rings, Icon-only buttons without labels |
+| 2 | Touch & Interaction | CRITICAL | `ux` | Min size 44×44px, 8px+ spacing, Loading feedback | Reliance on hover only, Instant state changes (0ms) |
+| 3 | Performance | HIGH | `ux` | WebP/AVIF, Lazy loading, Reserve space (CLS &lt; 0.1) | Layout thrashing, Cumulative Layout Shift |
+| 4 | Style Selection | HIGH | `style`, `product` | Match product type, Consistency, SVG icons (no emoji) | Mixing flat & skeuomorphic randomly, Emoji as icons |
+| 5 | Layout & Responsive | HIGH | `ux` | Mobile-first breakpoints, Viewport meta, No horizontal scroll | Horizontal scroll, Fixed px container widths, Disable zoom |
+| 6 | Typography & Color | MEDIUM | `typography`, `color` | Base 16px, Line-height 1.5, Semantic color tokens | Text &lt; 12px body, Gray-on-gray, Raw hex in components |
+| 7 | Animation | MEDIUM | `ux` | Duration 150–300ms, Motion conveys meaning, Spatial continuity | Decorative-only animation, Animating width/height, No reduced-motion |
+| 8 | Forms & Feedback | MEDIUM | `ux` | Visible labels, Error near field, Helper text, Progressive disclosure | Placeholder-only label, Errors only at top, Overwhelm upfront |
+| 9 | Navigation Patterns | HIGH | `ux` | Predictable back, Bottom nav ≤5, Deep linking | Overloaded nav, Broken back behavior, No deep links |
+| 10 | Charts & Data | LOW | `chart` | Legends, Tooltips, Accessible colors | Relying on color alone to convey meaning |
+
+## Quick Reference
+
+### 1. Accessibility (CRITICAL)
+
+- `color-contrast` - Minimum 4.5:1 ratio for normal text (large text 3:1); Material Design
+- `focus-states` - Visible focus rings on interactive elements (2–4px; Apple HIG, MD)
+- `alt-text` - Descriptive alt text for meaningful images
+- `aria-labels` - aria-label for icon-only buttons; accessibilityLabel in native (Apple HIG)
+- `keyboard-nav` - Tab order matches visual order; full keyboard support (Apple HIG)
+- `form-labels` - Use label with for attribute
+- `skip-links` - Skip to main content for keyboard users
+- `heading-hierarchy` - Sequential h1→h6, no level skip
+- `color-not-only` - Don't convey info by color alone (add icon/text)
+- `dynamic-type` - Support system text scaling; avoid truncation as text grows (Apple Dynamic Type, MD)
+- `reduced-motion` - Respect prefers-reduced-motion; reduce/disable animations when requested (Apple Reduced Motion API, MD)
+- `voiceover-sr` - Meaningful accessibilityLabel/accessibilityHint; logical reading order for VoiceOver/screen readers (Apple HIG, MD)
+- `escape-routes` - Provide cancel/back in modals and multi-step flows (Apple HIG)
+- `keyboard-shortcuts` - Preserve system and a11y shortcuts; offer keyboard alternatives for drag-and-drop (Apple HIG)
+
+### 2. Touch & Interaction (CRITICAL)
+
+- `touch-target-size` - Min 44×44pt (Apple) / 48×48dp (Material); extend hit area beyond visual bounds if needed
+- `touch-spacing` - Minimum 8px/8dp gap between touch targets (Apple HIG, MD)
+- `hover-vs-tap` - Use click/tap for primary interactions; don't rely on hover alone
+- `loading-buttons` - Disable button during async operations; show spinner or progress
+- `error-feedback` - Clear error messages near problem
+- `cursor-pointer` - Add cursor-pointer to clickable elements (Web)
+- `gesture-conflicts` - Avoid horizontal swipe on main content; prefer vertical scroll
+- `tap-delay` - Use touch-action: manipulation to reduce 300ms delay (Web)
+- `standard-gestures` - Use platform standard gestures consistently; don't redefine (e.g. swipe-back, pinch-zoom) (Apple HIG)
+- `system-gestures` - Don't block system gestures (Control Center, back swipe, etc.) (Apple HIG)
+- `press-feedback` - Visual feedback on press (ripple/highlight; MD state layers)
+- `haptic-feedback` - Use haptic for confirmations and important actions; avoid overuse (Apple HIG)
+- `gesture-alternative` - Don't rely on gesture-only interactions; always provide visible controls for critical actions
+- `safe-area-awareness` - Keep primary touch targets away from notch, Dynamic Island, gesture bar and screen edges
+- `no-precision-required` - Avoid requiring pixel-perfect taps on small icons or thin edges
+- `swipe-clarity` - Swipe actions must show clear affordance or hint (chevron, label, tutorial)
+- `drag-threshold` - Use a movement threshold before starting drag to avoid accidental drags
+
+### 3. Performance (HIGH)
+
+- `image-optimization` - Use WebP/AVIF, responsive images (srcset/sizes), lazy load non-critical assets
+- `image-dimension` - Declare width/height or use aspect-ratio to prevent layout shift (Core Web Vitals: CLS)
+- `font-loading` - Use font-display: swap/optional to avoid invisible text (FOIT); reserve space to reduce layout shift (MD)
+- `font-preload` - Preload only critical fonts; avoid overusing preload on every variant
+- `critical-css` - Prioritize above-the-fold CSS (inline critical CSS or early-loaded stylesheet)
+- `lazy-loading` - Lazy load non-hero components via dynamic import / route-level splitting
+- `bundle-splitting` - Split code by route/feature (React Suspense / Next.js dynamic) to reduce initial load and TTI
+- `third-party-scripts` - Load third-party scripts async/defer; audit and remove unnecessary ones (MD)
+- `reduce-reflows` - Avoid frequent layout reads/writes; batch DOM reads then writes
+- `content-jumping` - Reserve space for async content to avoid layout jumps (Core Web Vitals: CLS)
+- `lazy-load-below-fold` - Use loading="lazy" for below-the-fold images and heavy media
+- `virtualize-lists` - Virtualize lists with 50+ items to improve memory efficiency and scroll performance
+- `main-thread-budget` - Keep per-frame work under ~16ms for 60fps; move heavy tasks off main thread (HIG, MD)
+- `progressive-loading` - Use skeleton screens / shimmer instead of long blocking spinners for >1s operations (Apple HIG)
+- `input-latency` - Keep input latency under ~100ms for taps/scrolls (Material responsiveness standard)
+- `tap-feedback-speed` - Provide visual feedback within 100ms of tap (Apple HIG)
+- `debounce-throttle` - Use debounce/throttle for high-frequency events (scroll, resize, input)
+- `offline-support` - Provide offline state messaging and basic fallback (PWA / mobile)
+- `network-fallback` - Offer degraded modes for slow networks (lower-res images, fewer animations)
+
+### 4. Style Selection (HIGH)
+
+- `style-match` - Match style to product type (use `--design-system` for recommendations)
+- `consistency` - Use same style across all pages
+- `no-emoji-icons` - Use SVG icons (Heroicons, Lucide), not emojis
+- `color-palette-from-product` - Choose palette from product/industry (search `--domain color`)
+- `effects-match-style` - Shadows, blur, radius aligned with chosen style (glass / flat / clay etc.)
+- `platform-adaptive` - Respect platform idioms (iOS HIG vs Material): navigation, controls, typography, motion
+- `state-clarity` - Make hover/pressed/disabled states visually distinct while staying on-style (Material state layers)
+- `elevation-consistent` - Use a consistent elevation/shadow scale for cards, sheets, modals; avoid random shadow values
+- `dark-mode-pairing` - Design light/dark variants together to keep brand, contrast, and style consistent
+- `icon-style-consistent` - Use one icon set/visual language (stroke width, corner radius) across the product
+- `system-controls` - Prefer native/system controls over fully custom ones; only customize when branding requires it (Apple HIG)
+- `blur-purpose` - Use blur to indicate background dismissal (modals, sheets), not as decoration (Apple HIG)
+- `primary-action` - Each screen should have only one primary CTA; secondary actions visually subordinate (Apple HIG)
+
+### 5. Layout & Responsive (HIGH)
+
+- `viewport-meta` - width=device-width initial-scale=1 (never disable zoom)
+- `mobile-first` - Design mobile-first, then scale up to tablet and desktop
+- `breakpoint-consistency` - Use systematic breakpoints (e.g. 375 / 768 / 1024 / 1440)
+- `readable-font-size` - Minimum 16px body text on mobile (avoids iOS auto-zoom)
+- `line-length-control` - Mobile 35–60 chars per line; desktop 60–75 chars
+- `horizontal-scroll` - No horizontal scroll on mobile; ensure content fits viewport width
+- `spacing-scale` - Use 4pt/8dp incremental spacing system (Material Design)
+- `touch-density` - Keep component spacing comfortable for touch: not cramped, not causing mis-taps
+- `container-width` - Consistent max-width on desktop (max-w-6xl / 7xl)
+- `z-index-management` - Define layered z-index scale (e.g. 0 / 10 / 20 / 40 / 100 / 1000)
+- `fixed-element-offset` - Fixed navbar/bottom bar must reserve safe padding for underlying content
+- `scroll-behavior` - Avoid nested scroll regions that interfere with the main scroll experience
+- `viewport-units` - Prefer min-h-dvh over 100vh on mobile
+- `orientation-support` - Keep layout readable and operable in landscape mode
+- `content-priority` - Show core content first on mobile; fold or hide secondary content
+- `visual-hierarchy` - Establish hierarchy via size, spacing, contrast — not color alone
+
+### 6. Typography & Color (MEDIUM)
+
+- `line-height` - Use 1.5-1.75 for body text
+- `line-length` - Limit to 65-75 characters per line
+- `font-pairing` - Match heading/body font personalities
+- `font-scale` - Consistent type scale (e.g. 12 14 16 18 24 32)
+- `contrast-readability` - Darker text on light backgrounds (e.g. slate-900 on white)
+- `text-styles-system` - Use platform type system: iOS 11 Dynamic Type styles / Material 5 type roles (display, headline, title, body, label) (HIG, MD)
+- `weight-hierarchy` - Use font-weight to reinforce hierarchy: Bold headings (600–700), Regular body (400), Medium labels (500) (MD)
+- `color-semantic` - Define semantic color tokens (primary, secondary, error, surface, on-surface) not raw hex in components (Material color system)
+- `color-dark-mode` - Dark mode uses desaturated / lighter tonal variants, not inverted colors; test contrast separately (HIG, MD)
+- `color-accessible-pairs` - Foreground/background pairs must meet 4.5:1 (AA) or 7:1 (AAA); use tools to verify (WCAG, MD)
+- `color-not-decorative-only` - Functional color (error red, success green) must include icon/text; avoid color-only meaning (HIG, MD)
+- `truncation-strategy` - Prefer wrapping over truncation; when truncating use ellipsis and provide full text via tooltip/expand (Apple HIG)
+- `letter-spacing` - Respect default letter-spacing per platform; avoid tight tracking on body text (HIG, MD)
+- `number-tabular` - Use tabular/monospaced figures for data columns, prices, and timers to prevent layout shift
+- `whitespace-balance` - Use whitespace intentionally to group related items and separate sections; avoid visual clutter (Apple HIG)
+
+### 7. Animation (MEDIUM)
+
+- `duration-timing` - Use 150–300ms for micro-interactions; complex transitions ≤400ms; avoid >500ms (MD)
+- `transform-performance` - Use transform/opacity only; avoid animating width/height/top/left
+- `loading-states` - Show skeleton or progress indicator when loading exceeds 300ms
+- `excessive-motion` - Animate 1-2 key elements per view max
+- `easing` - Use ease-out for entering, ease-in for exiting; avoid linear for UI transitions
+- `motion-meaning` - Every animation must express a cause-effect relationship, not just be decorative (Apple HIG)
+- `state-transition` - State changes (hover / active / expanded / collapsed / modal) should animate smoothly, not snap
+- `continuity` - Page/screen transitions should maintain spatial continuity (shared element, directional slide) (Apple HIG)
+- `parallax-subtle` - Use parallax sparingly; must respect reduced-motion and not cause disorientation (Apple HIG)
+- `spring-physics` - Prefer spring/physics-based curves over linear or cubic-bezier for natural feel (Apple HIG fluid animations)
+- `exit-faster-than-enter` - Exit animations shorter than enter (~60–70% of enter duration) to feel responsive (MD motion)
+- `stagger-sequence` - Stagger list/grid item entrance by 30–50ms per item; avoid all-at-once or too-slow reveals (MD)
+- `shared-element-transition` - Use shared element / hero transitions for visual continuity between screens (MD, HIG)
+- `interruptible` - Animations must be interruptible; user tap/gesture cancels in-progress animation immediately (Apple HIG)
+- `no-blocking-animation` - Never block user input during an animation; UI must stay interactive (Apple HIG)
+- `fade-crossfade` - Use crossfade for content replacement within the same container (MD)
+- `scale-feedback` - Subtle scale (0.95–1.05) on press for tappable cards/buttons; restore on release (HIG, MD)
+- `gesture-feedback` - Drag, swipe, and pinch must provide real-time visual response tracking the finger (MD Motion)
+- `hierarchy-motion` - Use translate/scale direction to express hierarchy: enter from below = deeper, exit upward = back (MD)
+- `motion-consistency` - Unify duration/easing tokens globally; all animations share the same rhythm and feel
+- `opacity-threshold` - Fading elements should not linger below opacity 0.2; either fade fully or remain visible
+- `modal-motion` - Modals/sheets should animate from their trigger source (scale+fade or slide-in) for spatial context (HIG, MD)
+- `navigation-direction` - Forward navigation animates left/up; backward animates right/down — keep direction logically consistent (HIG)
+- `layout-shift-avoid` - Animations must not cause layout reflow or CLS; use transform for position changes
+
+### 8. Forms & Feedback (MEDIUM)
+
+- `input-labels` - Visible label per input (not placeholder-only)
+- `error-placement` - Show error below the related field
+- `submit-feedback` - Loading then success/error state on submit
+- `required-indicators` - Mark required fields (e.g. asterisk)
+- `empty-states` - Helpful message and action when no content
+- `toast-dismiss` - Auto-dismiss toasts in 3-5s
+- `confirmation-dialogs` - Confirm before destructive actions
+- `input-helper-text` - Provide persistent helper text below complex inputs, not just placeholder (Material Design)
+- `disabled-states` - Disabled elements use reduced opacity (0.38–0.5) + cursor change + semantic attribute (MD)
+- `progressive-disclosure` - Reveal complex options progressively; don't overwhelm users upfront (Apple HIG)
+- `inline-validation` - Validate on blur (not keystroke); show error only after user finishes input (MD)
+- `input-type-keyboard` - Use semantic input types (email, tel, number) to trigger the correct mobile keyboard (HIG, MD)
+- `password-toggle` - Provide show/hide toggle for password fields (MD)
+- `autofill-support` - Use autocomplete / textContentType attributes so the system can autofill (HIG, MD)
+- `undo-support` - Allow undo for destructive or bulk actions (e.g. "Undo delete" toast) (Apple HIG)
+- `success-feedback` - Confirm completed actions with brief visual feedback (checkmark, toast, color flash) (MD)
+- `error-recovery` - Error messages must include a clear recovery path (retry, edit, help link) (HIG, MD)
+- `multi-step-progress` - Multi-step flows show step indicator or progress bar; allow back navigation (MD)
+- `form-autosave` - Long forms should auto-save drafts to prevent data loss on accidental dismissal (Apple HIG)
+- `sheet-dismiss-confirm` - Confirm before dismissing a sheet/modal with unsaved changes (Apple HIG)
+- `error-clarity` - Error messages must state cause + how to fix (not just "Invalid input") (HIG, MD)
+- `field-grouping` - Group related fields logically (fieldset/legend or visual grouping) (MD)
+- `read-only-distinction` - Read-only state should be visually and semantically different from disabled (MD)
+- `focus-management` - After submit error, auto-focus the first invalid field (WCAG, MD)
+- `error-summary` - For multiple errors, show summary at top with anchor links to each field (WCAG)
+- `touch-friendly-input` - Mobile input height ≥44px to meet touch target requirements (Apple HIG)
+- `destructive-emphasis` - Destructive actions use semantic danger color (red) and are visually separated from primary actions (HIG, MD)
+- `toast-accessibility` - Toasts must not steal focus; use aria-live="polite" for screen reader announcement (WCAG)
+- `aria-live-errors` - Form errors use aria-live region or role="alert" to notify screen readers (WCAG)
+- `contrast-feedback` - Error and success state colors must meet 4.5:1 contrast ratio (WCAG, MD)
+- `timeout-feedback` - Request timeout must show clear feedback with retry option (MD)
+
+### 9. Navigation Patterns (HIGH)
+
+- `bottom-nav-limit` - Bottom navigation max 5 items; use labels with icons (Material Design)
+- `drawer-usage` - Use drawer/sidebar for secondary navigation, not primary actions (Material Design)
+- `back-behavior` - Back navigation must be predictable and consistent; preserve scroll/state (Apple HIG, MD)
+- `deep-linking` - All key screens must be reachable via deep link / URL for sharing and notifications (Apple HIG, MD)
+- `tab-bar-ios` - iOS: use bottom Tab Bar for top-level navigation (Apple HIG)
+- `top-app-bar-android` - Android: use Top App Bar with navigation icon for primary structure (Material Design)
+- `nav-label-icon` - Navigation items must have both icon and text label; icon-only nav harms discoverability (MD)
+- `nav-state-active` - Current location must be visually highlighted (color, weight, indicator) in navigation (HIG, MD)
+- `nav-hierarchy` - Primary nav (tabs/bottom bar) vs secondary nav (drawer/settings) must be clearly separated (MD)
+- `modal-escape` - Modals and sheets must offer a clear close/dismiss affordance; swipe-down to dismiss on mobile (Apple HIG)
+- `search-accessible` - Search must be easily reachable (top bar or tab); provide recent/suggested queries (MD)
+- `breadcrumb-web` - Web: use breadcrumbs for 3+ level deep hierarchies to aid orientation (MD)
+- `state-preservation` - Navigating back must restore previous scroll position, filter state, and input (HIG, MD)
+- `gesture-nav-support` - Support system gesture navigation (iOS swipe-back, Android predictive back) without conflict (HIG, MD)
+- `tab-badge` - Use badges on nav items sparingly to indicate unread/pending; clear after user visits (HIG, MD)
+- `overflow-menu` - When actions exceed available space, use overflow/more menu instead of cramming (MD)
+- `bottom-nav-top-level` - Bottom nav is for top-level screens only; never nest sub-navigation inside it (MD)
+- `adaptive-navigation` - Large screens (≥1024px) prefer sidebar; small screens use bottom/top nav (Material Adaptive)
+- `back-stack-integrity` - Never silently reset the navigation stack or unexpectedly jump to home (HIG, MD)
+- `navigation-consistency` - Navigation placement must stay the same across all pages; don't change by page type
+- `avoid-mixed-patterns` - Don't mix Tab + Sidebar + Bottom Nav at the same hierarchy level
+- `modal-vs-navigation` - Modals must not be used for primary navigation flows; they break the user's path (HIG)
+- `focus-on-route-change` - After page transition, move focus to main content region for screen reader users (WCAG)
+- `persistent-nav` - Core navigation must remain reachable from deep pages; don't hide it entirely in sub-flows (HIG, MD)
+- `destructive-nav-separation` - Dangerous actions (delete account, logout) must be visually and spatially separated from normal nav items (HIG, MD)
+- `empty-nav-state` - When a nav destination is unavailable, explain why instead of silently hiding it (MD)
+
+### 10. Charts & Data (LOW)
+
+- `chart-type` - Match chart type to data type (trend → line, comparison → bar, proportion → pie/donut)
+- `color-guidance` - Use accessible color palettes; avoid red/green only pairs for colorblind users (WCAG, MD)
+- `data-table` - Provide table alternative for accessibility; charts alone are not screen-reader friendly (WCAG)
+- `pattern-texture` - Supplement color with patterns, textures, or shapes so data is distinguishable without color (WCAG, MD)
+- `legend-visible` - Always show legend; position near the chart, not detached below a scroll fold (MD)
+- `tooltip-on-interact` - Provide tooltips/data labels on hover (Web) or tap (mobile) showing exact values (HIG, MD)
+- `axis-labels` - Label axes with units and readable scale; avoid truncated or rotated labels on mobile
+- `responsive-chart` - Charts must reflow or simplify on small screens (e.g. horizontal bar instead of vertical, fewer ticks)
+- `empty-data-state` - Show meaningful empty state when no data exists ("No data yet" + guidance), not a blank chart (MD)
+- `loading-chart` - Use skeleton or shimmer placeholder while chart data loads; don't show an empty axis frame
+- `animation-optional` - Chart entrance animations must respect prefers-reduced-motion; data should be readable immediately (HIG)
+- `large-dataset` - For 1000+ data points, aggregate or sample; provide drill-down for detail instead of rendering all (MD)
+- `number-formatting` - Use locale-aware formatting for numbers, dates, currencies on axes and labels (HIG, MD)
+- `touch-target-chart` - Interactive chart elements (points, segments) must have ≥44pt tap area or expand on touch (Apple HIG)
+- `no-pie-overuse` - Avoid pie/donut for >5 categories; switch to bar chart for clarity
+- `contrast-data` - Data lines/bars vs background ≥3:1; data text labels ≥4.5:1 (WCAG)
+- `legend-interactive` - Legends should be clickable to toggle series visibility (MD)
+- `direct-labeling` - For small datasets, label values directly on the chart to reduce eye travel
+- `tooltip-keyboard` - Tooltip content must be keyboard-reachable and not rely on hover alone (WCAG)
+- `sortable-table` - Data tables must support sorting with aria-sort indicating current sort state (WCAG)
+- `axis-readability` - Axis ticks must not be cramped; maintain readable spacing, auto-skip on small screens
+- `data-density` - Limit information density per chart to avoid cognitive overload; split into multiple charts if needed
+- `trend-emphasis` - Emphasize data trends over decoration; avoid heavy gradients/shadows that obscure the data
+- `gridline-subtle` - Grid lines should be low-contrast (e.g. gray-200) so they don't compete with data
+- `focusable-elements` - Interactive chart elements (points, bars, slices) must be keyboard-navigable (WCAG)
+- `screen-reader-summary` - Provide a text summary or aria-label describing the chart's key insight for screen readers (WCAG)
+- `error-state-chart` - Data load failure must show error message with retry action, not a broken/empty chart
+- `export-option` - For data-heavy products, offer CSV/image export of chart data
+- `drill-down-consistency` - Drill-down interactions must maintain a clear back-path and hierarchy breadcrumb
+- `time-scale-clarity` - Time series charts must clearly label time granularity (day/week/month) and allow switching
+
+## How to Use
+
+Search specific domains using the CLI tool below.
+
+---
+
+## Prerequisites
+
+Check if Python is installed:
+
+```bash
+python3 --version || python --version
+```
+
+If Python is not installed, install it based on user's OS:
+
+**macOS:**
+```bash
+brew install python3
+```
+
+**Ubuntu/Debian:**
+```bash
+sudo apt update && sudo apt install python3
+```
+
+**Windows:**
+```powershell
+winget install Python.Python.3.12
+```
+
+---
+
+## How to Use This Skill
+
+Use this skill when the user requests any of the following:
+
+| Scenario | Trigger Examples | Start From |
+|----------|-----------------|------------|
+| **New project / page** | "Build a landing page", "Build a dashboard" | Step 1 → Step 2 (design system) |
+| **New component** | "Create a pricing card", "Add a modal" | Step 3 (domain search: style, ux) |
+| **Choose style / color / font** | "What style fits a fintech app?", "Recommend a color palette" | Step 2 (design system) |
+| **Review existing UI** | "Review this page for UX issues", "Check accessibility" | Quick Reference checklist above |
+| **Fix a UI bug** | "Button hover is broken", "Layout shifts on load" | Quick Reference → relevant section |
+| **Improve / optimize** | "Make this faster", "Improve mobile experience" | Step 3 (domain search: ux, react) |
+| **Implement dark mode** | "Add dark mode support" | Step 3 (domain: style "dark mode") |
+| **Add charts / data viz** | "Add an analytics dashboard chart" | Step 3 (domain: chart) |
+| **Stack best practices** | "React performance tips"、"SwiftUI navigation" | Step 4 (stack search) |
+
+Follow this workflow:
+
+### Step 1: Analyze User Requirements
+
+Extract key information from user request:
+- **Product type**: Entertainment (social, video, music, gaming), Tool (scanner, editor, converter), Productivity (task manager, notes, calendar), or hybrid
+- **Target audience**: C-end consumer users; consider age group, usage context (commute, leisure, work)
+- **Style keywords**: playful, vibrant, minimal, dark mode, content-first, immersive, etc.
+- **Stack**: React Native (this project's only tech stack)
+
+### Step 2: Generate Design System (REQUIRED)
+
+**Always start with `--design-system`** to get comprehensive recommendations with reasoning:
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "<product_type> <industry> <keywords>" --design-system [-p "Project Name"]
+```
+
+This command:
+1. Searches domains in parallel (product, style, color, landing, typography)
+2. Applies reasoning rules from `ui-reasoning.csv` to select best matches
+3. Returns complete design system: pattern, style, colors, typography, effects
+4. Includes anti-patterns to avoid
+
+**Example:**
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "beauty spa wellness service" --design-system -p "Serenity Spa"
+```
+
+### Step 2b: Persist Design System (Master + Overrides Pattern)
+
+To save the design system for **hierarchical retrieval across sessions**, add `--persist`:
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Project Name"
+```
+
+This creates:
+- `design-system/MASTER.md` — Global Source of Truth with all design rules
+- `design-system/pages/` — Folder for page-specific overrides
+
+**With page-specific override:**
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Project Name" --page "dashboard"
+```
+
+This also creates:
+- `design-system/pages/dashboard.md` — Page-specific deviations from Master
+
+**How hierarchical retrieval works:**
+1. When building a specific page (e.g., "Checkout"), first check `design-system/pages/checkout.md`
+2. If the page file exists, its rules **override** the Master file
+3. If not, use `design-system/MASTER.md` exclusively
+
+**Context-aware retrieval prompt:**
+```
+I am building the [Page Name] page. Please read design-system/MASTER.md.
+Also check if design-system/pages/[page-name].md exists.
+If the page file exists, prioritize its rules.
+If not, use the Master rules exclusively.
+Now, generate the code...
+```
+
+### Step 3: Supplement with Detailed Searches (as needed)
+
+After getting the design system, use domain searches to get additional details:
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "<keyword>" --domain <domain> [-n <max_results>]
+```
+
+**When to use detailed searches:**
+
+| Need | Domain | Example |
+|------|--------|---------|
+| Product type patterns | `product` | `--domain product "entertainment social"` |
+| More style options | `style` | `--domain style "glassmorphism dark"` |
+| Color palettes | `color` | `--domain color "entertainment vibrant"` |
+| Font pairings | `typography` | `--domain typography "playful modern"` |
+| Chart recommendations | `chart` | `--domain chart "real-time dashboard"` |
+| UX best practices | `ux` | `--domain ux "animation accessibility"` |
+| Alternative fonts | `typography` | `--domain typography "elegant luxury"` |
+| Individual Google Fonts | `google-fonts` | `--domain google-fonts "sans serif popular variable"` |
+| Landing structure | `landing` | `--domain landing "hero social-proof"` |
+| React Native perf | `react` | `--domain react "rerender memo list"` |
+| App interface a11y | `web` | `--domain web "accessibilityLabel touch safe-areas"` |
+| AI prompt / CSS keywords | `prompt` | `--domain prompt "minimalism"` |
+
+### Step 4: Stack Guidelines (React Native)
+
+Get React Native implementation-specific best practices:
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "<keyword>" --stack react-native
+```
+
+---
+
+## Search Reference
+
+### Available Domains
+
+| Domain | Use For | Example Keywords |
+|--------|---------|------------------|
+| `product` | Product type recommendations | SaaS, e-commerce, portfolio, healthcare, beauty, service |
+| `style` | UI styles, colors, effects | glassmorphism, minimalism, dark mode, brutalism |
+| `typography` | Font pairings, Google Fonts | elegant, playful, professional, modern |
+| `color` | Color palettes by product type | saas, ecommerce, healthcare, beauty, fintech, service |
+| `landing` | Page structure, CTA strategies | hero, hero-centric, testimonial, pricing, social-proof |
+| `chart` | Chart types, library recommendations | trend, comparison, timeline, funnel, pie |
+| `ux` | Best practices, anti-patterns | animation, accessibility, z-index, loading |
+| `google-fonts` | Individual Google Fonts lookup | sans serif, monospace, japanese, variable font, popular |
+| `react` | React/Next.js performance | waterfall, bundle, suspense, memo, rerender, cache |
+| `web` | App interface guidelines (iOS/Android/React Native) | accessibilityLabel, touch targets, safe areas, Dynamic Type |
+| `prompt` | AI prompts, CSS keywords | (style name) |
+
+### Available Stacks
+
+| Stack | Focus |
+|-------|-------|
+| `react-native` | Components, Navigation, Lists |
+
+---
+
+## Example Workflow
+
+**User request:** "Make an AI search homepage."
+
+### Step 1: Analyze Requirements
+- Product type: Tool (AI search engine)
+- Target audience: C-end users looking for fast, intelligent search
+- Style keywords: modern, minimal, content-first, dark mode
+- Stack: React Native
+
+### Step 2: Generate Design System (REQUIRED)
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "AI search tool modern minimal" --design-system -p "AI Search"
+```
+
+**Output:** Complete design system with pattern, style, colors, typography, effects, and anti-patterns.
+
+### Step 3: Supplement with Detailed Searches (as needed)
+
+```bash
+# Get style options for a modern tool product
+python3 skills/ui-ux-pro-max/scripts/search.py "minimalism dark mode" --domain style
+
+# Get UX best practices for search interaction and loading
+python3 skills/ui-ux-pro-max/scripts/search.py "search loading animation" --domain ux
+```
+
+### Step 4: Stack Guidelines
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "list performance navigation" --stack react-native
+```
+
+**Then:** Synthesize design system + detailed searches and implement the design.
+
+---
+
+## Output Formats
+
+The `--design-system` flag supports two output formats:
+
+```bash
+# ASCII box (default) - best for terminal display
+python3 skills/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system
+
+# Markdown - best for documentation
+python3 skills/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system -f markdown
+```
+
+---
+
+## Tips for Better Results
+
+### Query Strategy
+
+- Use **multi-dimensional keywords** — combine product + industry + tone + density: `"entertainment social vibrant content-dense"` not just `"app"`
+- Try different keywords for the same need: `"playful neon"` → `"vibrant dark"` → `"content-first minimal"`
+- Use `--design-system` first for full recommendations, then `--domain` to deep-dive any dimension you're unsure about
+- Always add `--stack react-native` for implementation-specific guidance
+
+### Common Sticking Points
+
+| Problem | What to Do |
+|---------|------------|
+| Can't decide on style/color | Re-run `--design-system` with different keywords |
+| Dark mode contrast issues | Quick Reference §6: `color-dark-mode` + `color-accessible-pairs` |
+| Animations feel unnatural | Quick Reference §7: `spring-physics` + `easing` + `exit-faster-than-enter` |
+| Form UX is poor | Quick Reference §8: `inline-validation` + `error-clarity` + `focus-management` |
+| Navigation feels confusing | Quick Reference §9: `nav-hierarchy` + `bottom-nav-limit` + `back-behavior` |
+| Layout breaks on small screens | Quick Reference §5: `mobile-first` + `breakpoint-consistency` |
+| Performance / jank | Quick Reference §3: `virtualize-lists` + `main-thread-budget` + `debounce-throttle` |
+
+### Pre-Delivery Checklist
+
+- Run `--domain ux "animation accessibility z-index loading"` as a UX validation pass before implementation
+- Run through Quick Reference **§1–§3** (CRITICAL + HIGH) as a final review
+- Test on 375px (small phone) and landscape orientation
+- Verify behavior with **reduced-motion** enabled and **Dynamic Type** at largest size
+- Check dark mode contrast independently (don't assume light mode values work)
+- Confirm all touch targets ≥44pt and no content hidden behind safe areas
+
+---
+
+## Common Rules for Professional UI
+
+These are frequently overlooked issues that make UI look unprofessional:
+Scope notice: The rules below are for App UI (iOS/Android/React Native/Flutter), not desktop-web interaction patterns.
+
+### Icons & Visual Elements
+
+| Rule | Standard | Avoid | Why It Matters |
+|------|----------|--------|----------------|
+| **No Emoji as Structural Icons** | Use vector-based icons (e.g., Lucide, react-native-vector-icons, @expo/vector-icons). | Using emojis (🎨 🚀 ⚙️) for navigation, settings, or system controls. | Emojis are font-dependent, inconsistent across platforms, and cannot be controlled via design tokens. |
+| **Vector-Only Assets** | Use SVG or platform vector icons that scale cleanly and support theming. | Raster PNG icons that blur or pixelate. | Ensures scalability, crisp rendering, and dark/light mode adaptability. |
+| **Stable Interaction States** | Use color, opacity, or elevation transitions for press states without changing layout bounds. | Layout-shifting transforms that move surrounding content or trigger visual jitter. | Prevents unstable interactions and preserves smooth motion/perceived quality on mobile. |
+| **Correct Brand Logos** | Use official brand assets and follow their usage guidelines (spacing, color, clear space). | Guessing logo paths, recoloring unofficially, or modifying proportions. | Prevents brand misuse and ensures legal/platform compliance. |
+| **Consistent Icon Sizing** | Define icon sizes as design tokens (e.g., icon-sm, icon-md = 24pt, icon-lg). | Mixing arbitrary values like 20pt / 24pt / 28pt randomly. | Maintains rhythm and visual hierarchy across the interface. |
+| **Stroke Consistency** | Use a consistent stroke width within the same visual layer (e.g., 1.5px or 2px). | Mixing thick and thin stroke styles arbitrarily. | Inconsistent strokes reduce perceived polish and cohesion. |
+| **Filled vs Outline Discipline** | Use one icon style per hierarchy level. | Mixing filled and outline icons at the same hierarchy level. | Maintains semantic clarity and stylistic coherence. |
+| **Touch Target Minimum** | Minimum 44×44pt interactive area (use hitSlop if icon is smaller). | Small icons without expanded tap area. | Meets accessibility and platform usability standards. |
+| **Icon Alignment** | Align icons to text baseline and maintain consistent padding. | Misaligned icons or inconsistent spacing around them. | Prevents subtle visual imbalance that reduces perceived quality. |
+| **Icon Contrast** | Follow WCAG contrast standards: 4.5:1 for small elements, 3:1 minimum for larger UI glyphs. | Low-contrast icons that blend into the background. | Ensures accessibility in both light and dark modes. |
+
+
+### Interaction (App)
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **Tap feedback** | Provide clear pressed feedback (ripple/opacity/elevation) within 80-150ms | No visual response on tap |
+| **Animation timing** | Keep micro-interactions around 150-300ms with platform-native easing | Instant transitions or slow animations (>500ms) |
+| **Accessibility focus** | Ensure screen reader focus order matches visual order and labels are descriptive | Unlabeled controls or confusing focus traversal |
+| **Disabled state clarity** | Use disabled semantics (`disabled`/native disabled props), reduced emphasis, and no tap action | Controls that look tappable but do nothing |
+| **Touch target minimum** | Keep tap areas >=44x44pt (iOS) or >=48x48dp (Android), expand hit area when icon is smaller | Tiny tap targets or icon-only hit areas without padding |
+| **Gesture conflict prevention** | Keep one primary gesture per region and avoid nested tap/drag conflicts | Overlapping gestures causing accidental actions |
+| **Semantic native controls** | Prefer native interactive primitives (`Button`, `Pressable`, platform equivalents) with proper accessibility roles | Generic containers used as primary controls without semantics |
+
+### Light/Dark Mode Contrast
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **Surface readability (light)** | Keep cards/surfaces clearly separated from background with sufficient opacity/elevation | Overly transparent surfaces that blur hierarchy |
+| **Text contrast (light)** | Maintain body text contrast >=4.5:1 against light surfaces | Low-contrast gray body text |
+| **Text contrast (dark)** | Maintain primary text contrast >=4.5:1 and secondary text >=3:1 on dark surfaces | Dark mode text that blends into background |
+| **Border and divider visibility** | Ensure separators are visible in both themes (not just light mode) | Theme-specific borders disappearing in one mode |
+| **State contrast parity** | Keep pressed/focused/disabled states equally distinguishable in light and dark themes | Defining interaction states for one theme only |
+| **Token-driven theming** | Use semantic color tokens mapped per theme across app surfaces/text/icons | Hardcoded per-screen hex values |
+| **Scrim and modal legibility** | Use a modal scrim strong enough to isolate foreground content (typically 40-60% black) | Weak scrim that leaves background visually competing |
+
+### Layout & Spacing
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **Safe-area compliance** | Respect top/bottom safe areas for all fixed headers, tab bars, and CTA bars | Placing fixed UI under notch, status bar, or gesture area |
+| **System bar clearance** | Add spacing for status/navigation bars and gesture home indicator | Let tappable content collide with OS chrome |
+| **Consistent content width** | Keep predictable content width per device class (phone/tablet) | Mixing arbitrary widths between screens |
+| **8dp spacing rhythm** | Use a consistent 4/8dp spacing system for padding/gaps/section spacing | Random spacing increments with no rhythm |
+| **Readable text measure** | Keep long-form text readable on large devices (avoid edge-to-edge paragraphs on tablets) | Full-width long text that hurts readability |
+| **Section spacing hierarchy** | Define clear vertical rhythm tiers (e.g., 16/24/32/48) by hierarchy | Similar UI levels with inconsistent spacing |
+| **Adaptive gutters by breakpoint** | Increase horizontal insets on larger widths and in landscape | Same narrow gutter on all device sizes/orientations |
+| **Scroll and fixed element coexistence** | Add bottom/top content insets so lists are not hidden behind fixed bars | Scroll content obscured by sticky headers/footers |
+
+---
+
+## Pre-Delivery Checklist
+
+Before delivering UI code, verify these items:
+Scope notice: This checklist is for App UI (iOS/Android/React Native/Flutter).
+
+### Visual Quality
+- [ ] No emojis used as icons (use SVG instead)
+- [ ] All icons come from a consistent icon family and style
+- [ ] Official brand assets are used with correct proportions and clear space
+- [ ] Pressed-state visuals do not shift layout bounds or cause jitter
+- [ ] Semantic theme tokens are used consistently (no ad-hoc per-screen hardcoded colors)
+
+### Interaction
+- [ ] All tappable elements provide clear pressed feedback (ripple/opacity/elevation)
+- [ ] Touch targets meet minimum size (>=44x44pt iOS, >=48x48dp Android)
+- [ ] Micro-interaction timing stays in the 150-300ms range with native-feeling easing
+- [ ] Disabled states are visually clear and non-interactive
+- [ ] Screen reader focus order matches visual order, and interactive labels are descriptive
+- [ ] Gesture regions avoid nested/conflicting interactions (tap/drag/back-swipe conflicts)
+
+### Light/Dark Mode
+- [ ] Primary text contrast >=4.5:1 in both light and dark mode
+- [ ] Secondary text contrast >=3:1 in both light and dark mode
+- [ ] Dividers/borders and interaction states are distinguishable in both modes
+- [ ] Modal/drawer scrim opacity is strong enough to preserve foreground legibility (typically 40-60% black)
+- [ ] Both themes are tested before delivery (not inferred from a single theme)
+
+### Layout
+- [ ] Safe areas are respected for headers, tab bars, and bottom CTA bars
+- [ ] Scroll content is not hidden behind fixed/sticky bars
+- [ ] Verified on small phone, large phone, and tablet (portrait + landscape)
+- [ ] Horizontal insets/gutters adapt correctly by device size and orientation
+- [ ] 4/8dp spacing rhythm is maintained across component, section, and page levels
+- [ ] Long-form text measure remains readable on larger devices (no edge-to-edge paragraphs)
+
+### Accessibility
+- [ ] All meaningful images/icons have accessibility labels
+- [ ] Form fields have labels, hints, and clear error messages
+- [ ] Color is not the only indicator
+- [ ] Reduced motion and dynamic text size are supported without layout breakage
+- [ ] Accessibility traits/roles/states (selected, disabled, expanded) are announced correctly

.agents/skills/ui-ux-pro-max/data

@@ -0,0 +1 @@
+../../../src/ui-ux-pro-max/data

.agents/skills/ui-ux-pro-max/scripts

@@ -0,0 +1 @@
+../../../src/ui-ux-pro-max/scripts

.dockerignore

@@ -0,0 +1,16 @@
+# Exclude node_modules from frontend
+App/frontend/node_modules
+
+# Exclude models and venv from backend
+App/backend/models
+App/backend/venv
+App/backend/__pycache__
+App/backend/*.wav
+
+# Exclude other build artifacts
+dist
+static
+.git
+.gitignore
+.dockerignore
+README.md

.gitignore

@@ -0,0 +1,21 @@
+# Build artifacts
+App/frontend/dist
+App/backend/static
+App/backend/build
+App/backend/dist
+eReader_App/
+*.spec
+node_modules
+venv
+.env*
+*.pyc
+__pycache__
+
+# Models (downloaded in Docker or manually)
+App/backend/models/
+App/backend/*.wav
+
+# Editor files
+.vscode
+.idea
+.DS_Store

App/backend/check.py

@@ -0,0 +1,19 @@
+import io
+import wave
+from piper import PiperVoice
+
+voice = PiperVoice.load("models/en_US-lessac-medium.onnx")
+
+audio_stream = io.BytesIO()
+
+with wave.open(audio_stream, "wb") as wav_file:
+    wav_file.setnchannels(1)
+    wav_file.setsampwidth(2)
+    wav_file.setframerate(voice.config.sample_rate)
+    voice.synthesize("test message", wav_file)
+
+data = audio_stream.getvalue()
+print("Wav size:", len(data))
+with open("test.wav", "wb") as f:
+    f.write(data)
+print("Wrote to test.wav")

App/backend/download_model.py

@@ -0,0 +1,50 @@
+import os
+import urllib.request
+
+BASE = "https://huggingface.co/rhasspy/piper-voices/resolve/v1.0.0"
+
+VOICES = [
+    # US English — faster low quality versions
+    {"locale": "en/en_US", "name": "lessac",               "quality": "low"},
+    # US English — existing medium
+    {"locale": "en/en_US", "name": "lessac",               "quality": "medium"},
+    {"locale": "en/en_US", "name": "libritts_r",           "quality": "medium"},
+    # US English — new medium
+    {"locale": "en/en_US", "name": "joe",                  "quality": "medium"},
+    # British English — new
+    {"locale": "en/en_GB", "name": "alan",                 "quality": "medium"},
+    {"locale": "en/en_GB", "name": "northern_english_male","quality": "medium"},
+    {"locale": "en/en_GB", "name": "semaine",              "quality": "medium"},
+    {"locale": "en/en_GB", "name": "southern_english_female","quality": "low"},
+]
+
+MODEL_DIR = "models"
+os.makedirs(MODEL_DIR, exist_ok=True)
+
+def download(url, path):
+    print(f"  Downloading {url}")
+    urllib.request.urlretrieve(url, path)
+    print(f"  Saved → {path}")
+
+for v in VOICES:
+    locale, name, quality = v["locale"], v["name"], v["quality"]
+    # derive the locale tag from the path (e.g. "en/en_US" → "en_US")
+    locale_tag = locale.split("/")[-1]
+    model_id   = f"{locale_tag}-{name}-{quality}"
+    base_url   = f"{BASE}/{locale}/{name}/{quality}/{model_id}"
+
+    model_path  = os.path.join(MODEL_DIR, f"{model_id}.onnx")
+    config_path = os.path.join(MODEL_DIR, f"{model_id}.onnx.json")
+
+    print(f"\n[{model_id}]")
+    if not os.path.exists(model_path):
+        download(f"{base_url}.onnx?download=true", model_path)
+    else:
+        print("  model already present, skipping.")
+
+    if not os.path.exists(config_path):
+        download(f"{base_url}.onnx.json?download=true", config_path)
+    else:
+        print("  config already present, skipping.")
+
+print("\nAll models ready.")

App/backend/main.py

@@ -0,0 +1,110 @@
+import os
+import io
+import wave
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from fastapi.responses import Response
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel
+from typing import Optional
+from piper import PiperVoice
+from piper.config import SynthesisConfig
+import onnxruntime
+import logging
+import numpy as np
+
+log = logging.getLogger("uvicorn.error")
+
+# Monkey-patch ONNX Runtime to auto-detect best provider (GPU > CPU)
+_original_inf_session = onnxruntime.InferenceSession
+
+def _patched_inf_session(path_or_bytes, sess_options=None, providers=None, *args, **kwargs):
+    if providers is None or providers == ['CPUExecutionProvider']:
+        available = onnxruntime.get_available_providers()
+        preferred = [p for p in ['CUDAExecutionProvider', 'DmlExecutionProvider', 'CoreMLExecutionProvider'] if p in available]
+        preferred.append('CPUExecutionProvider')
+        providers = preferred
+    return _original_inf_session(path_or_bytes, sess_options, providers, *args, **kwargs)
+
+onnxruntime.InferenceSession = _patched_inf_session
+
+# Load models lazily
+voices = {}
+
+def get_voice(voice_id: str):
+    global voices
+    if voice_id not in voices:
+        model_path = f"models/{voice_id}.onnx"
+        if not os.path.exists(model_path):
+            raise Exception(f"Model not found: {model_path}. Run download_model.py")
+        voices[voice_id] = PiperVoice.load(model_path)
+    return voices[voice_id]
+
+def synthesize_text(text: str, voice_id: str, speaker_id: Optional[int] = None) -> bytes:
+    """Core synthesis helper - returns raw WAV bytes."""
+    v = get_voice(voice_id)
+    audio_stream = io.BytesIO()
+    with wave.open(audio_stream, "wb") as wav_file:
+        wav_file.setnchannels(1)
+        wav_file.setsampwidth(2)
+        wav_file.setframerate(v.config.sample_rate)
+        syn_config = None
+        if speaker_id is not None and v.config.num_speakers > 1:
+            syn_config = SynthesisConfig(speaker_id=speaker_id)
+        for chunk in v.synthesize(text, syn_config=syn_config):
+            int16 = (np.clip(chunk.audio_float_array, -1.0, 1.0) * 32767).astype(np.int16)
+            wav_file.writeframes(int16.tobytes())
+    return audio_stream.getvalue()
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Startup: pre-load the default voice and JIT the ONNX model."""
+    log.info("Warming up TTS engine...")
+    try:
+        synthesize_text("Ready.", "en_US-lessac-low")
+        log.info("TTS engine warm and ready.")
+    except Exception as e:
+        log.error(f"Warmup failed: {e}")
+    yield  # App runs here
+
+app = FastAPI(lifespan=lifespan)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+class SynthesizeRequest(BaseModel):
+    text: str
+    voice_id: str = "en_US-lessac-low"
+    speaker_id: Optional[int] = None
+
+@app.post("/synthesize")
+def synthesize(req: SynthesizeRequest):
+    audio_data = synthesize_text(req.text, req.voice_id, req.speaker_id)
+    return Response(content=audio_data, media_type="audio/wav")
+
+@app.get("/ping")
+def ping():
+    return {"status": "ok"}
+
+@app.get("/warmup")
+def warmup():
+    """Wake the server and ensure the model is loaded. Called on page load."""
+    try:
+        get_voice("en_US-lessac-low")
+        return {"status": "ready"}
+    except Exception as e:
+        return {"status": "error", "detail": str(e)}
+
+# Serve frontend static files if they exist (Docker / single-server mode)
+if os.path.exists("static"):
+    app.mount("/", StaticFiles(directory="static", html=True), name="static")
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="127.0.0.1", port=8000, log_level="info")

App/backend/requirements.txt

@@ -0,0 +1,25 @@
+annotated-doc==0.0.4
+annotated-types==0.7.0
+anyio==4.12.1
+click==8.3.1
+colorama==0.4.6
+fastapi==0.133.1
+flatbuffers==25.12.19
+h11==0.16.0
+idna==3.11
+mpmath==1.3.0
+numpy==2.4.2
+onnxruntime==1.24.2
+packaging==26.0
+piper-tts==1.4.1
+protobuf==6.33.5
+pydantic==2.12.5
+pydantic_core==2.41.5
+pydub==0.25.1
+python-multipart==0.0.22
+starlette==0.52.1
+sympy==1.14.0
+typing-inspection==0.4.2
+typing_extensions==4.15.0
+uvicorn==0.41.0
+aiofiles==24.1.0

App/backend/test_piper.py

@@ -0,0 +1,14 @@
+from piper import PiperVoice
+
+v = PiperVoice.load("models/en_US-libritts_r-medium.onnx")
+try:
+    chunks = list(v.synthesize("test", speaker_id=5))
+    print("SUCCESS with speaker_id kwarg")
+except Exception as e:
+    print("FAILED with speaker_id kwarg:", e)
+    
+try:
+    chunks = list(v.synthesize("test", synthesize_args={"speaker_id": 5}))
+    print("SUCCESS with synthesize_args")
+except Exception as e:
+    print("FAILED with synthesize_args:", e)

App/frontend/.agent/skills/ui-ux-pro-max/SKILL.md

@@ -0,0 +1,659 @@
+---
+name: ui-ux-pro-max
+description: "UI/UX design intelligence for web and mobile. Includes 50+ styles, 161 color palettes, 57 font pairings, 161 product types, 99 UX guidelines, and 25 chart types across 10 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui, and HTML/CSS). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, and check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, and mobile app. Elements: button, modal, navbar, sidebar, card, table, form, and chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, and flat design. Topics: color systems, accessibility, animation, layout, typography, font pairing, spacing, interaction states, shadow, and gradient. Integrations: shadcn/ui MCP for component search and examples."
+---
+
+# UI/UX Pro Max - Design Intelligence
+
+Comprehensive design guide for web and mobile applications. Contains 50+ styles, 161 color palettes, 57 font pairings, 161 product types with reasoning rules, 99 UX guidelines, and 25 chart types across 10 technology stacks. Searchable database with priority-based recommendations.
+
+## When to Apply
+
+This Skill should be used when the task involves **UI structure, visual design decisions, interaction patterns, or user experience quality control**.
+
+### Must Use
+
+This Skill must be invoked in the following situations:
+
+- Designing new pages (Landing Page, Dashboard, Admin, SaaS, Mobile App)
+- Creating or refactoring UI components (buttons, modals, forms, tables, charts, etc.)
+- Choosing color schemes, typography systems, spacing standards, or layout systems
+- Reviewing UI code for user experience, accessibility, or visual consistency
+- Implementing navigation structures, animations, or responsive behavior
+- Making product-level design decisions (style, information hierarchy, brand expression)
+- Improving perceived quality, clarity, or usability of interfaces
+
+### Recommended
+
+This Skill is recommended in the following situations:
+
+- UI looks "not professional enough" but the reason is unclear
+- Receiving feedback on usability or experience
+- Pre-launch UI quality optimization
+- Aligning cross-platform design (Web / iOS / Android)
+- Building design systems or reusable component libraries
+
+### Skip
+
+This Skill is not needed in the following situations:
+
+- Pure backend logic development
+- Only involving API or database design
+- Performance optimization unrelated to the interface
+- Infrastructure or DevOps work
+- Non-visual scripts or automation tasks
+
+**Decision criteria**: If the task will change how a feature **looks, feels, moves, or is interacted with**, this Skill should be used.
+
+## Rule Categories by Priority
+
+*For human/AI reference: follow priority 1→10 to decide which rule category to focus on first; use `--domain <Domain>` to query details when needed. Scripts do not read this table.*
+
+| Priority | Category | Impact | Domain | Key Checks (Must Have) | Anti-Patterns (Avoid) |
+|----------|----------|--------|--------|------------------------|------------------------|
+| 1 | Accessibility | CRITICAL | `ux` | Contrast 4.5:1, Alt text, Keyboard nav, Aria-labels | Removing focus rings, Icon-only buttons without labels |
+| 2 | Touch & Interaction | CRITICAL | `ux` | Min size 44×44px, 8px+ spacing, Loading feedback | Reliance on hover only, Instant state changes (0ms) |
+| 3 | Performance | HIGH | `ux` | WebP/AVIF, Lazy loading, Reserve space (CLS &lt; 0.1) | Layout thrashing, Cumulative Layout Shift |
+| 4 | Style Selection | HIGH | `style`, `product` | Match product type, Consistency, SVG icons (no emoji) | Mixing flat & skeuomorphic randomly, Emoji as icons |
+| 5 | Layout & Responsive | HIGH | `ux` | Mobile-first breakpoints, Viewport meta, No horizontal scroll | Horizontal scroll, Fixed px container widths, Disable zoom |
+| 6 | Typography & Color | MEDIUM | `typography`, `color` | Base 16px, Line-height 1.5, Semantic color tokens | Text &lt; 12px body, Gray-on-gray, Raw hex in components |
+| 7 | Animation | MEDIUM | `ux` | Duration 150–300ms, Motion conveys meaning, Spatial continuity | Decorative-only animation, Animating width/height, No reduced-motion |
+| 8 | Forms & Feedback | MEDIUM | `ux` | Visible labels, Error near field, Helper text, Progressive disclosure | Placeholder-only label, Errors only at top, Overwhelm upfront |
+| 9 | Navigation Patterns | HIGH | `ux` | Predictable back, Bottom nav ≤5, Deep linking | Overloaded nav, Broken back behavior, No deep links |
+| 10 | Charts & Data | LOW | `chart` | Legends, Tooltips, Accessible colors | Relying on color alone to convey meaning |
+
+## Quick Reference
+
+### 1. Accessibility (CRITICAL)
+
+- `color-contrast` - Minimum 4.5:1 ratio for normal text (large text 3:1); Material Design
+- `focus-states` - Visible focus rings on interactive elements (2–4px; Apple HIG, MD)
+- `alt-text` - Descriptive alt text for meaningful images
+- `aria-labels` - aria-label for icon-only buttons; accessibilityLabel in native (Apple HIG)
+- `keyboard-nav` - Tab order matches visual order; full keyboard support (Apple HIG)
+- `form-labels` - Use label with for attribute
+- `skip-links` - Skip to main content for keyboard users
+- `heading-hierarchy` - Sequential h1→h6, no level skip
+- `color-not-only` - Don't convey info by color alone (add icon/text)
+- `dynamic-type` - Support system text scaling; avoid truncation as text grows (Apple Dynamic Type, MD)
+- `reduced-motion` - Respect prefers-reduced-motion; reduce/disable animations when requested (Apple Reduced Motion API, MD)
+- `voiceover-sr` - Meaningful accessibilityLabel/accessibilityHint; logical reading order for VoiceOver/screen readers (Apple HIG, MD)
+- `escape-routes` - Provide cancel/back in modals and multi-step flows (Apple HIG)
+- `keyboard-shortcuts` - Preserve system and a11y shortcuts; offer keyboard alternatives for drag-and-drop (Apple HIG)
+
+### 2. Touch & Interaction (CRITICAL)
+
+- `touch-target-size` - Min 44×44pt (Apple) / 48×48dp (Material); extend hit area beyond visual bounds if needed
+- `touch-spacing` - Minimum 8px/8dp gap between touch targets (Apple HIG, MD)
+- `hover-vs-tap` - Use click/tap for primary interactions; don't rely on hover alone
+- `loading-buttons` - Disable button during async operations; show spinner or progress
+- `error-feedback` - Clear error messages near problem
+- `cursor-pointer` - Add cursor-pointer to clickable elements (Web)
+- `gesture-conflicts` - Avoid horizontal swipe on main content; prefer vertical scroll
+- `tap-delay` - Use touch-action: manipulation to reduce 300ms delay (Web)
+- `standard-gestures` - Use platform standard gestures consistently; don't redefine (e.g. swipe-back, pinch-zoom) (Apple HIG)
+- `system-gestures` - Don't block system gestures (Control Center, back swipe, etc.) (Apple HIG)
+- `press-feedback` - Visual feedback on press (ripple/highlight; MD state layers)
+- `haptic-feedback` - Use haptic for confirmations and important actions; avoid overuse (Apple HIG)
+- `gesture-alternative` - Don't rely on gesture-only interactions; always provide visible controls for critical actions
+- `safe-area-awareness` - Keep primary touch targets away from notch, Dynamic Island, gesture bar and screen edges
+- `no-precision-required` - Avoid requiring pixel-perfect taps on small icons or thin edges
+- `swipe-clarity` - Swipe actions must show clear affordance or hint (chevron, label, tutorial)
+- `drag-threshold` - Use a movement threshold before starting drag to avoid accidental drags
+
+### 3. Performance (HIGH)
+
+- `image-optimization` - Use WebP/AVIF, responsive images (srcset/sizes), lazy load non-critical assets
+- `image-dimension` - Declare width/height or use aspect-ratio to prevent layout shift (Core Web Vitals: CLS)
+- `font-loading` - Use font-display: swap/optional to avoid invisible text (FOIT); reserve space to reduce layout shift (MD)
+- `font-preload` - Preload only critical fonts; avoid overusing preload on every variant
+- `critical-css` - Prioritize above-the-fold CSS (inline critical CSS or early-loaded stylesheet)
+- `lazy-loading` - Lazy load non-hero components via dynamic import / route-level splitting
+- `bundle-splitting` - Split code by route/feature (React Suspense / Next.js dynamic) to reduce initial load and TTI
+- `third-party-scripts` - Load third-party scripts async/defer; audit and remove unnecessary ones (MD)
+- `reduce-reflows` - Avoid frequent layout reads/writes; batch DOM reads then writes
+- `content-jumping` - Reserve space for async content to avoid layout jumps (Core Web Vitals: CLS)
+- `lazy-load-below-fold` - Use loading="lazy" for below-the-fold images and heavy media
+- `virtualize-lists` - Virtualize lists with 50+ items to improve memory efficiency and scroll performance
+- `main-thread-budget` - Keep per-frame work under ~16ms for 60fps; move heavy tasks off main thread (HIG, MD)
+- `progressive-loading` - Use skeleton screens / shimmer instead of long blocking spinners for >1s operations (Apple HIG)
+- `input-latency` - Keep input latency under ~100ms for taps/scrolls (Material responsiveness standard)
+- `tap-feedback-speed` - Provide visual feedback within 100ms of tap (Apple HIG)
+- `debounce-throttle` - Use debounce/throttle for high-frequency events (scroll, resize, input)
+- `offline-support` - Provide offline state messaging and basic fallback (PWA / mobile)
+- `network-fallback` - Offer degraded modes for slow networks (lower-res images, fewer animations)
+
+### 4. Style Selection (HIGH)
+
+- `style-match` - Match style to product type (use `--design-system` for recommendations)
+- `consistency` - Use same style across all pages
+- `no-emoji-icons` - Use SVG icons (Heroicons, Lucide), not emojis
+- `color-palette-from-product` - Choose palette from product/industry (search `--domain color`)
+- `effects-match-style` - Shadows, blur, radius aligned with chosen style (glass / flat / clay etc.)
+- `platform-adaptive` - Respect platform idioms (iOS HIG vs Material): navigation, controls, typography, motion
+- `state-clarity` - Make hover/pressed/disabled states visually distinct while staying on-style (Material state layers)
+- `elevation-consistent` - Use a consistent elevation/shadow scale for cards, sheets, modals; avoid random shadow values
+- `dark-mode-pairing` - Design light/dark variants together to keep brand, contrast, and style consistent
+- `icon-style-consistent` - Use one icon set/visual language (stroke width, corner radius) across the product
+- `system-controls` - Prefer native/system controls over fully custom ones; only customize when branding requires it (Apple HIG)
+- `blur-purpose` - Use blur to indicate background dismissal (modals, sheets), not as decoration (Apple HIG)
+- `primary-action` - Each screen should have only one primary CTA; secondary actions visually subordinate (Apple HIG)
+
+### 5. Layout & Responsive (HIGH)
+
+- `viewport-meta` - width=device-width initial-scale=1 (never disable zoom)
+- `mobile-first` - Design mobile-first, then scale up to tablet and desktop
+- `breakpoint-consistency` - Use systematic breakpoints (e.g. 375 / 768 / 1024 / 1440)
+- `readable-font-size` - Minimum 16px body text on mobile (avoids iOS auto-zoom)
+- `line-length-control` - Mobile 35–60 chars per line; desktop 60–75 chars
+- `horizontal-scroll` - No horizontal scroll on mobile; ensure content fits viewport width
+- `spacing-scale` - Use 4pt/8dp incremental spacing system (Material Design)
+- `touch-density` - Keep component spacing comfortable for touch: not cramped, not causing mis-taps
+- `container-width` - Consistent max-width on desktop (max-w-6xl / 7xl)
+- `z-index-management` - Define layered z-index scale (e.g. 0 / 10 / 20 / 40 / 100 / 1000)
+- `fixed-element-offset` - Fixed navbar/bottom bar must reserve safe padding for underlying content
+- `scroll-behavior` - Avoid nested scroll regions that interfere with the main scroll experience
+- `viewport-units` - Prefer min-h-dvh over 100vh on mobile
+- `orientation-support` - Keep layout readable and operable in landscape mode
+- `content-priority` - Show core content first on mobile; fold or hide secondary content
+- `visual-hierarchy` - Establish hierarchy via size, spacing, contrast — not color alone
+
+### 6. Typography & Color (MEDIUM)
+
+- `line-height` - Use 1.5-1.75 for body text
+- `line-length` - Limit to 65-75 characters per line
+- `font-pairing` - Match heading/body font personalities
+- `font-scale` - Consistent type scale (e.g. 12 14 16 18 24 32)
+- `contrast-readability` - Darker text on light backgrounds (e.g. slate-900 on white)
+- `text-styles-system` - Use platform type system: iOS 11 Dynamic Type styles / Material 5 type roles (display, headline, title, body, label) (HIG, MD)
+- `weight-hierarchy` - Use font-weight to reinforce hierarchy: Bold headings (600–700), Regular body (400), Medium labels (500) (MD)
+- `color-semantic` - Define semantic color tokens (primary, secondary, error, surface, on-surface) not raw hex in components (Material color system)
+- `color-dark-mode` - Dark mode uses desaturated / lighter tonal variants, not inverted colors; test contrast separately (HIG, MD)
+- `color-accessible-pairs` - Foreground/background pairs must meet 4.5:1 (AA) or 7:1 (AAA); use tools to verify (WCAG, MD)
+- `color-not-decorative-only` - Functional color (error red, success green) must include icon/text; avoid color-only meaning (HIG, MD)
+- `truncation-strategy` - Prefer wrapping over truncation; when truncating use ellipsis and provide full text via tooltip/expand (Apple HIG)
+- `letter-spacing` - Respect default letter-spacing per platform; avoid tight tracking on body text (HIG, MD)
+- `number-tabular` - Use tabular/monospaced figures for data columns, prices, and timers to prevent layout shift
+- `whitespace-balance` - Use whitespace intentionally to group related items and separate sections; avoid visual clutter (Apple HIG)
+
+### 7. Animation (MEDIUM)
+
+- `duration-timing` - Use 150–300ms for micro-interactions; complex transitions ≤400ms; avoid >500ms (MD)
+- `transform-performance` - Use transform/opacity only; avoid animating width/height/top/left
+- `loading-states` - Show skeleton or progress indicator when loading exceeds 300ms
+- `excessive-motion` - Animate 1-2 key elements per view max
+- `easing` - Use ease-out for entering, ease-in for exiting; avoid linear for UI transitions
+- `motion-meaning` - Every animation must express a cause-effect relationship, not just be decorative (Apple HIG)
+- `state-transition` - State changes (hover / active / expanded / collapsed / modal) should animate smoothly, not snap
+- `continuity` - Page/screen transitions should maintain spatial continuity (shared element, directional slide) (Apple HIG)
+- `parallax-subtle` - Use parallax sparingly; must respect reduced-motion and not cause disorientation (Apple HIG)
+- `spring-physics` - Prefer spring/physics-based curves over linear or cubic-bezier for natural feel (Apple HIG fluid animations)
+- `exit-faster-than-enter` - Exit animations shorter than enter (~60–70% of enter duration) to feel responsive (MD motion)
+- `stagger-sequence` - Stagger list/grid item entrance by 30–50ms per item; avoid all-at-once or too-slow reveals (MD)
+- `shared-element-transition` - Use shared element / hero transitions for visual continuity between screens (MD, HIG)
+- `interruptible` - Animations must be interruptible; user tap/gesture cancels in-progress animation immediately (Apple HIG)
+- `no-blocking-animation` - Never block user input during an animation; UI must stay interactive (Apple HIG)
+- `fade-crossfade` - Use crossfade for content replacement within the same container (MD)
+- `scale-feedback` - Subtle scale (0.95–1.05) on press for tappable cards/buttons; restore on release (HIG, MD)
+- `gesture-feedback` - Drag, swipe, and pinch must provide real-time visual response tracking the finger (MD Motion)
+- `hierarchy-motion` - Use translate/scale direction to express hierarchy: enter from below = deeper, exit upward = back (MD)
+- `motion-consistency` - Unify duration/easing tokens globally; all animations share the same rhythm and feel
+- `opacity-threshold` - Fading elements should not linger below opacity 0.2; either fade fully or remain visible
+- `modal-motion` - Modals/sheets should animate from their trigger source (scale+fade or slide-in) for spatial context (HIG, MD)
+- `navigation-direction` - Forward navigation animates left/up; backward animates right/down — keep direction logically consistent (HIG)
+- `layout-shift-avoid` - Animations must not cause layout reflow or CLS; use transform for position changes
+
+### 8. Forms & Feedback (MEDIUM)
+
+- `input-labels` - Visible label per input (not placeholder-only)
+- `error-placement` - Show error below the related field
+- `submit-feedback` - Loading then success/error state on submit
+- `required-indicators` - Mark required fields (e.g. asterisk)
+- `empty-states` - Helpful message and action when no content
+- `toast-dismiss` - Auto-dismiss toasts in 3-5s
+- `confirmation-dialogs` - Confirm before destructive actions
+- `input-helper-text` - Provide persistent helper text below complex inputs, not just placeholder (Material Design)
+- `disabled-states` - Disabled elements use reduced opacity (0.38–0.5) + cursor change + semantic attribute (MD)
+- `progressive-disclosure` - Reveal complex options progressively; don't overwhelm users upfront (Apple HIG)
+- `inline-validation` - Validate on blur (not keystroke); show error only after user finishes input (MD)
+- `input-type-keyboard` - Use semantic input types (email, tel, number) to trigger the correct mobile keyboard (HIG, MD)
+- `password-toggle` - Provide show/hide toggle for password fields (MD)
+- `autofill-support` - Use autocomplete / textContentType attributes so the system can autofill (HIG, MD)
+- `undo-support` - Allow undo for destructive or bulk actions (e.g. "Undo delete" toast) (Apple HIG)
+- `success-feedback` - Confirm completed actions with brief visual feedback (checkmark, toast, color flash) (MD)
+- `error-recovery` - Error messages must include a clear recovery path (retry, edit, help link) (HIG, MD)
+- `multi-step-progress` - Multi-step flows show step indicator or progress bar; allow back navigation (MD)
+- `form-autosave` - Long forms should auto-save drafts to prevent data loss on accidental dismissal (Apple HIG)
+- `sheet-dismiss-confirm` - Confirm before dismissing a sheet/modal with unsaved changes (Apple HIG)
+- `error-clarity` - Error messages must state cause + how to fix (not just "Invalid input") (HIG, MD)
+- `field-grouping` - Group related fields logically (fieldset/legend or visual grouping) (MD)
+- `read-only-distinction` - Read-only state should be visually and semantically different from disabled (MD)
+- `focus-management` - After submit error, auto-focus the first invalid field (WCAG, MD)
+- `error-summary` - For multiple errors, show summary at top with anchor links to each field (WCAG)
+- `touch-friendly-input` - Mobile input height ≥44px to meet touch target requirements (Apple HIG)
+- `destructive-emphasis` - Destructive actions use semantic danger color (red) and are visually separated from primary actions (HIG, MD)
+- `toast-accessibility` - Toasts must not steal focus; use aria-live="polite" for screen reader announcement (WCAG)
+- `aria-live-errors` - Form errors use aria-live region or role="alert" to notify screen readers (WCAG)
+- `contrast-feedback` - Error and success state colors must meet 4.5:1 contrast ratio (WCAG, MD)
+- `timeout-feedback` - Request timeout must show clear feedback with retry option (MD)
+
+### 9. Navigation Patterns (HIGH)
+
+- `bottom-nav-limit` - Bottom navigation max 5 items; use labels with icons (Material Design)
+- `drawer-usage` - Use drawer/sidebar for secondary navigation, not primary actions (Material Design)
+- `back-behavior` - Back navigation must be predictable and consistent; preserve scroll/state (Apple HIG, MD)
+- `deep-linking` - All key screens must be reachable via deep link / URL for sharing and notifications (Apple HIG, MD)
+- `tab-bar-ios` - iOS: use bottom Tab Bar for top-level navigation (Apple HIG)
+- `top-app-bar-android` - Android: use Top App Bar with navigation icon for primary structure (Material Design)
+- `nav-label-icon` - Navigation items must have both icon and text label; icon-only nav harms discoverability (MD)
+- `nav-state-active` - Current location must be visually highlighted (color, weight, indicator) in navigation (HIG, MD)
+- `nav-hierarchy` - Primary nav (tabs/bottom bar) vs secondary nav (drawer/settings) must be clearly separated (MD)
+- `modal-escape` - Modals and sheets must offer a clear close/dismiss affordance; swipe-down to dismiss on mobile (Apple HIG)
+- `search-accessible` - Search must be easily reachable (top bar or tab); provide recent/suggested queries (MD)
+- `breadcrumb-web` - Web: use breadcrumbs for 3+ level deep hierarchies to aid orientation (MD)
+- `state-preservation` - Navigating back must restore previous scroll position, filter state, and input (HIG, MD)
+- `gesture-nav-support` - Support system gesture navigation (iOS swipe-back, Android predictive back) without conflict (HIG, MD)
+- `tab-badge` - Use badges on nav items sparingly to indicate unread/pending; clear after user visits (HIG, MD)
+- `overflow-menu` - When actions exceed available space, use overflow/more menu instead of cramming (MD)
+- `bottom-nav-top-level` - Bottom nav is for top-level screens only; never nest sub-navigation inside it (MD)
+- `adaptive-navigation` - Large screens (≥1024px) prefer sidebar; small screens use bottom/top nav (Material Adaptive)
+- `back-stack-integrity` - Never silently reset the navigation stack or unexpectedly jump to home (HIG, MD)
+- `navigation-consistency` - Navigation placement must stay the same across all pages; don't change by page type
+- `avoid-mixed-patterns` - Don't mix Tab + Sidebar + Bottom Nav at the same hierarchy level
+- `modal-vs-navigation` - Modals must not be used for primary navigation flows; they break the user's path (HIG)
+- `focus-on-route-change` - After page transition, move focus to main content region for screen reader users (WCAG)
+- `persistent-nav` - Core navigation must remain reachable from deep pages; don't hide it entirely in sub-flows (HIG, MD)
+- `destructive-nav-separation` - Dangerous actions (delete account, logout) must be visually and spatially separated from normal nav items (HIG, MD)
+- `empty-nav-state` - When a nav destination is unavailable, explain why instead of silently hiding it (MD)
+
+### 10. Charts & Data (LOW)
+
+- `chart-type` - Match chart type to data type (trend → line, comparison → bar, proportion → pie/donut)
+- `color-guidance` - Use accessible color palettes; avoid red/green only pairs for colorblind users (WCAG, MD)
+- `data-table` - Provide table alternative for accessibility; charts alone are not screen-reader friendly (WCAG)
+- `pattern-texture` - Supplement color with patterns, textures, or shapes so data is distinguishable without color (WCAG, MD)
+- `legend-visible` - Always show legend; position near the chart, not detached below a scroll fold (MD)
+- `tooltip-on-interact` - Provide tooltips/data labels on hover (Web) or tap (mobile) showing exact values (HIG, MD)
+- `axis-labels` - Label axes with units and readable scale; avoid truncated or rotated labels on mobile
+- `responsive-chart` - Charts must reflow or simplify on small screens (e.g. horizontal bar instead of vertical, fewer ticks)
+- `empty-data-state` - Show meaningful empty state when no data exists ("No data yet" + guidance), not a blank chart (MD)
+- `loading-chart` - Use skeleton or shimmer placeholder while chart data loads; don't show an empty axis frame
+- `animation-optional` - Chart entrance animations must respect prefers-reduced-motion; data should be readable immediately (HIG)
+- `large-dataset` - For 1000+ data points, aggregate or sample; provide drill-down for detail instead of rendering all (MD)
+- `number-formatting` - Use locale-aware formatting for numbers, dates, currencies on axes and labels (HIG, MD)
+- `touch-target-chart` - Interactive chart elements (points, segments) must have ≥44pt tap area or expand on touch (Apple HIG)
+- `no-pie-overuse` - Avoid pie/donut for >5 categories; switch to bar chart for clarity
+- `contrast-data` - Data lines/bars vs background ≥3:1; data text labels ≥4.5:1 (WCAG)
+- `legend-interactive` - Legends should be clickable to toggle series visibility (MD)
+- `direct-labeling` - For small datasets, label values directly on the chart to reduce eye travel
+- `tooltip-keyboard` - Tooltip content must be keyboard-reachable and not rely on hover alone (WCAG)
+- `sortable-table` - Data tables must support sorting with aria-sort indicating current sort state (WCAG)
+- `axis-readability` - Axis ticks must not be cramped; maintain readable spacing, auto-skip on small screens
+- `data-density` - Limit information density per chart to avoid cognitive overload; split into multiple charts if needed
+- `trend-emphasis` - Emphasize data trends over decoration; avoid heavy gradients/shadows that obscure the data
+- `gridline-subtle` - Grid lines should be low-contrast (e.g. gray-200) so they don't compete with data
+- `focusable-elements` - Interactive chart elements (points, bars, slices) must be keyboard-navigable (WCAG)
+- `screen-reader-summary` - Provide a text summary or aria-label describing the chart's key insight for screen readers (WCAG)
+- `error-state-chart` - Data load failure must show error message with retry action, not a broken/empty chart
+- `export-option` - For data-heavy products, offer CSV/image export of chart data
+- `drill-down-consistency` - Drill-down interactions must maintain a clear back-path and hierarchy breadcrumb
+- `time-scale-clarity` - Time series charts must clearly label time granularity (day/week/month) and allow switching
+
+## How to Use
+
+Search specific domains using the CLI tool below.
+
+---
+
+## Prerequisites
+
+Check if Python is installed:
+
+```bash
+python3 --version || python --version
+```
+
+If Python is not installed, install it based on user's OS:
+
+**macOS:**
+```bash
+brew install python3
+```
+
+**Ubuntu/Debian:**
+```bash
+sudo apt update && sudo apt install python3
+```
+
+**Windows:**
+```powershell
+winget install Python.Python.3.12
+```
+
+---
+
+## How to Use This Skill
+
+Use this skill when the user requests any of the following:
+
+| Scenario | Trigger Examples | Start From |
+|----------|-----------------|------------|
+| **New project / page** | "Build a landing page", "Build a dashboard" | Step 1 → Step 2 (design system) |
+| **New component** | "Create a pricing card", "Add a modal" | Step 3 (domain search: style, ux) |
+| **Choose style / color / font** | "What style fits a fintech app?", "Recommend a color palette" | Step 2 (design system) |
+| **Review existing UI** | "Review this page for UX issues", "Check accessibility" | Quick Reference checklist above |
+| **Fix a UI bug** | "Button hover is broken", "Layout shifts on load" | Quick Reference → relevant section |
+| **Improve / optimize** | "Make this faster", "Improve mobile experience" | Step 3 (domain search: ux, react) |
+| **Implement dark mode** | "Add dark mode support" | Step 3 (domain: style "dark mode") |
+| **Add charts / data viz** | "Add an analytics dashboard chart" | Step 3 (domain: chart) |
+| **Stack best practices** | "React performance tips"、"SwiftUI navigation" | Step 4 (stack search) |
+
+Follow this workflow:
+
+### Step 1: Analyze User Requirements
+
+Extract key information from user request:
+- **Product type**: Entertainment (social, video, music, gaming), Tool (scanner, editor, converter), Productivity (task manager, notes, calendar), or hybrid
+- **Target audience**: C-end consumer users; consider age group, usage context (commute, leisure, work)
+- **Style keywords**: playful, vibrant, minimal, dark mode, content-first, immersive, etc.
+- **Stack**: React Native (this project's only tech stack)
+
+### Step 2: Generate Design System (REQUIRED)
+
+**Always start with `--design-system`** to get comprehensive recommendations with reasoning:
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "<product_type> <industry> <keywords>" --design-system [-p "Project Name"]
+```
+
+This command:
+1. Searches domains in parallel (product, style, color, landing, typography)
+2. Applies reasoning rules from `ui-reasoning.csv` to select best matches
+3. Returns complete design system: pattern, style, colors, typography, effects
+4. Includes anti-patterns to avoid
+
+**Example:**
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "beauty spa wellness service" --design-system -p "Serenity Spa"
+```
+
+### Step 2b: Persist Design System (Master + Overrides Pattern)
+
+To save the design system for **hierarchical retrieval across sessions**, add `--persist`:
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Project Name"
+```
+
+This creates:
+- `design-system/MASTER.md` — Global Source of Truth with all design rules
+- `design-system/pages/` — Folder for page-specific overrides
+
+**With page-specific override:**
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Project Name" --page "dashboard"
+```
+
+This also creates:
+- `design-system/pages/dashboard.md` — Page-specific deviations from Master
+
+**How hierarchical retrieval works:**
+1. When building a specific page (e.g., "Checkout"), first check `design-system/pages/checkout.md`
+2. If the page file exists, its rules **override** the Master file
+3. If not, use `design-system/MASTER.md` exclusively
+
+**Context-aware retrieval prompt:**
+```
+I am building the [Page Name] page. Please read design-system/MASTER.md.
+Also check if design-system/pages/[page-name].md exists.
+If the page file exists, prioritize its rules.
+If not, use the Master rules exclusively.
+Now, generate the code...
+```
+
+### Step 3: Supplement with Detailed Searches (as needed)
+
+After getting the design system, use domain searches to get additional details:
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "<keyword>" --domain <domain> [-n <max_results>]
+```
+
+**When to use detailed searches:**
+
+| Need | Domain | Example |
+|------|--------|---------|
+| Product type patterns | `product` | `--domain product "entertainment social"` |
+| More style options | `style` | `--domain style "glassmorphism dark"` |
+| Color palettes | `color` | `--domain color "entertainment vibrant"` |
+| Font pairings | `typography` | `--domain typography "playful modern"` |
+| Chart recommendations | `chart` | `--domain chart "real-time dashboard"` |
+| UX best practices | `ux` | `--domain ux "animation accessibility"` |
+| Alternative fonts | `typography` | `--domain typography "elegant luxury"` |
+| Individual Google Fonts | `google-fonts` | `--domain google-fonts "sans serif popular variable"` |
+| Landing structure | `landing` | `--domain landing "hero social-proof"` |
+| React Native perf | `react` | `--domain react "rerender memo list"` |
+| App interface a11y | `web` | `--domain web "accessibilityLabel touch safe-areas"` |
+| AI prompt / CSS keywords | `prompt` | `--domain prompt "minimalism"` |
+
+### Step 4: Stack Guidelines (React Native)
+
+Get React Native implementation-specific best practices:
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "<keyword>" --stack react-native
+```
+
+---
+
+## Search Reference
+
+### Available Domains
+
+| Domain | Use For | Example Keywords |
+|--------|---------|------------------|
+| `product` | Product type recommendations | SaaS, e-commerce, portfolio, healthcare, beauty, service |
+| `style` | UI styles, colors, effects | glassmorphism, minimalism, dark mode, brutalism |
+| `typography` | Font pairings, Google Fonts | elegant, playful, professional, modern |
+| `color` | Color palettes by product type | saas, ecommerce, healthcare, beauty, fintech, service |
+| `landing` | Page structure, CTA strategies | hero, hero-centric, testimonial, pricing, social-proof |
+| `chart` | Chart types, library recommendations | trend, comparison, timeline, funnel, pie |
+| `ux` | Best practices, anti-patterns | animation, accessibility, z-index, loading |
+| `google-fonts` | Individual Google Fonts lookup | sans serif, monospace, japanese, variable font, popular |
+| `react` | React/Next.js performance | waterfall, bundle, suspense, memo, rerender, cache |
+| `web` | App interface guidelines (iOS/Android/React Native) | accessibilityLabel, touch targets, safe areas, Dynamic Type |
+| `prompt` | AI prompts, CSS keywords | (style name) |
+
+### Available Stacks
+
+| Stack | Focus |
+|-------|-------|
+| `react-native` | Components, Navigation, Lists |
+
+---
+
+## Example Workflow
+
+**User request:** "Make an AI search homepage."
+
+### Step 1: Analyze Requirements
+- Product type: Tool (AI search engine)
+- Target audience: C-end users looking for fast, intelligent search
+- Style keywords: modern, minimal, content-first, dark mode
+- Stack: React Native
+
+### Step 2: Generate Design System (REQUIRED)
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "AI search tool modern minimal" --design-system -p "AI Search"
+```
+
+**Output:** Complete design system with pattern, style, colors, typography, effects, and anti-patterns.
+
+### Step 3: Supplement with Detailed Searches (as needed)
+
+```bash
+# Get style options for a modern tool product
+python3 skills/ui-ux-pro-max/scripts/search.py "minimalism dark mode" --domain style
+
+# Get UX best practices for search interaction and loading
+python3 skills/ui-ux-pro-max/scripts/search.py "search loading animation" --domain ux
+```
+
+### Step 4: Stack Guidelines
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "list performance navigation" --stack react-native
+```
+
+**Then:** Synthesize design system + detailed searches and implement the design.
+
+---
+
+## Output Formats
+
+The `--design-system` flag supports two output formats:
+
+```bash
+# ASCII box (default) - best for terminal display
+python3 skills/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system
+
+# Markdown - best for documentation
+python3 skills/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system -f markdown
+```
+
+---
+
+## Tips for Better Results
+
+### Query Strategy
+
+- Use **multi-dimensional keywords** — combine product + industry + tone + density: `"entertainment social vibrant content-dense"` not just `"app"`
+- Try different keywords for the same need: `"playful neon"` → `"vibrant dark"` → `"content-first minimal"`
+- Use `--design-system` first for full recommendations, then `--domain` to deep-dive any dimension you're unsure about
+- Always add `--stack react-native` for implementation-specific guidance
+
+### Common Sticking Points
+
+| Problem | What to Do |
+|---------|------------|
+| Can't decide on style/color | Re-run `--design-system` with different keywords |
+| Dark mode contrast issues | Quick Reference §6: `color-dark-mode` + `color-accessible-pairs` |
+| Animations feel unnatural | Quick Reference §7: `spring-physics` + `easing` + `exit-faster-than-enter` |
+| Form UX is poor | Quick Reference §8: `inline-validation` + `error-clarity` + `focus-management` |
+| Navigation feels confusing | Quick Reference §9: `nav-hierarchy` + `bottom-nav-limit` + `back-behavior` |
+| Layout breaks on small screens | Quick Reference §5: `mobile-first` + `breakpoint-consistency` |
+| Performance / jank | Quick Reference §3: `virtualize-lists` + `main-thread-budget` + `debounce-throttle` |
+
+### Pre-Delivery Checklist
+
+- Run `--domain ux "animation accessibility z-index loading"` as a UX validation pass before implementation
+- Run through Quick Reference **§1–§3** (CRITICAL + HIGH) as a final review
+- Test on 375px (small phone) and landscape orientation
+- Verify behavior with **reduced-motion** enabled and **Dynamic Type** at largest size
+- Check dark mode contrast independently (don't assume light mode values work)
+- Confirm all touch targets ≥44pt and no content hidden behind safe areas
+
+---
+
+## Common Rules for Professional UI
+
+These are frequently overlooked issues that make UI look unprofessional:
+Scope notice: The rules below are for App UI (iOS/Android/React Native/Flutter), not desktop-web interaction patterns.
+
+### Icons & Visual Elements
+
+| Rule | Standard | Avoid | Why It Matters |
+|------|----------|--------|----------------|
+| **No Emoji as Structural Icons** | Use vector-based icons (e.g., Lucide, react-native-vector-icons, @expo/vector-icons). | Using emojis (🎨 🚀 ⚙️) for navigation, settings, or system controls. | Emojis are font-dependent, inconsistent across platforms, and cannot be controlled via design tokens. |
+| **Vector-Only Assets** | Use SVG or platform vector icons that scale cleanly and support theming. | Raster PNG icons that blur or pixelate. | Ensures scalability, crisp rendering, and dark/light mode adaptability. |
+| **Stable Interaction States** | Use color, opacity, or elevation transitions for press states without changing layout bounds. | Layout-shifting transforms that move surrounding content or trigger visual jitter. | Prevents unstable interactions and preserves smooth motion/perceived quality on mobile. |
+| **Correct Brand Logos** | Use official brand assets and follow their usage guidelines (spacing, color, clear space). | Guessing logo paths, recoloring unofficially, or modifying proportions. | Prevents brand misuse and ensures legal/platform compliance. |
+| **Consistent Icon Sizing** | Define icon sizes as design tokens (e.g., icon-sm, icon-md = 24pt, icon-lg). | Mixing arbitrary values like 20pt / 24pt / 28pt randomly. | Maintains rhythm and visual hierarchy across the interface. |
+| **Stroke Consistency** | Use a consistent stroke width within the same visual layer (e.g., 1.5px or 2px). | Mixing thick and thin stroke styles arbitrarily. | Inconsistent strokes reduce perceived polish and cohesion. |
+| **Filled vs Outline Discipline** | Use one icon style per hierarchy level. | Mixing filled and outline icons at the same hierarchy level. | Maintains semantic clarity and stylistic coherence. |
+| **Touch Target Minimum** | Minimum 44×44pt interactive area (use hitSlop if icon is smaller). | Small icons without expanded tap area. | Meets accessibility and platform usability standards. |
+| **Icon Alignment** | Align icons to text baseline and maintain consistent padding. | Misaligned icons or inconsistent spacing around them. | Prevents subtle visual imbalance that reduces perceived quality. |
+| **Icon Contrast** | Follow WCAG contrast standards: 4.5:1 for small elements, 3:1 minimum for larger UI glyphs. | Low-contrast icons that blend into the background. | Ensures accessibility in both light and dark modes. |
+
+
+### Interaction (App)
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **Tap feedback** | Provide clear pressed feedback (ripple/opacity/elevation) within 80-150ms | No visual response on tap |
+| **Animation timing** | Keep micro-interactions around 150-300ms with platform-native easing | Instant transitions or slow animations (>500ms) |
+| **Accessibility focus** | Ensure screen reader focus order matches visual order and labels are descriptive | Unlabeled controls or confusing focus traversal |
+| **Disabled state clarity** | Use disabled semantics (`disabled`/native disabled props), reduced emphasis, and no tap action | Controls that look tappable but do nothing |
+| **Touch target minimum** | Keep tap areas >=44x44pt (iOS) or >=48x48dp (Android), expand hit area when icon is smaller | Tiny tap targets or icon-only hit areas without padding |
+| **Gesture conflict prevention** | Keep one primary gesture per region and avoid nested tap/drag conflicts | Overlapping gestures causing accidental actions |
+| **Semantic native controls** | Prefer native interactive primitives (`Button`, `Pressable`, platform equivalents) with proper accessibility roles | Generic containers used as primary controls without semantics |
+
+### Light/Dark Mode Contrast
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **Surface readability (light)** | Keep cards/surfaces clearly separated from background with sufficient opacity/elevation | Overly transparent surfaces that blur hierarchy |
+| **Text contrast (light)** | Maintain body text contrast >=4.5:1 against light surfaces | Low-contrast gray body text |
+| **Text contrast (dark)** | Maintain primary text contrast >=4.5:1 and secondary text >=3:1 on dark surfaces | Dark mode text that blends into background |
+| **Border and divider visibility** | Ensure separators are visible in both themes (not just light mode) | Theme-specific borders disappearing in one mode |
+| **State contrast parity** | Keep pressed/focused/disabled states equally distinguishable in light and dark themes | Defining interaction states for one theme only |
+| **Token-driven theming** | Use semantic color tokens mapped per theme across app surfaces/text/icons | Hardcoded per-screen hex values |
+| **Scrim and modal legibility** | Use a modal scrim strong enough to isolate foreground content (typically 40-60% black) | Weak scrim that leaves background visually competing |
+
+### Layout & Spacing
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **Safe-area compliance** | Respect top/bottom safe areas for all fixed headers, tab bars, and CTA bars | Placing fixed UI under notch, status bar, or gesture area |
+| **System bar clearance** | Add spacing for status/navigation bars and gesture home indicator | Let tappable content collide with OS chrome |
+| **Consistent content width** | Keep predictable content width per device class (phone/tablet) | Mixing arbitrary widths between screens |
+| **8dp spacing rhythm** | Use a consistent 4/8dp spacing system for padding/gaps/section spacing | Random spacing increments with no rhythm |
+| **Readable text measure** | Keep long-form text readable on large devices (avoid edge-to-edge paragraphs on tablets) | Full-width long text that hurts readability |
+| **Section spacing hierarchy** | Define clear vertical rhythm tiers (e.g., 16/24/32/48) by hierarchy | Similar UI levels with inconsistent spacing |
+| **Adaptive gutters by breakpoint** | Increase horizontal insets on larger widths and in landscape | Same narrow gutter on all device sizes/orientations |
+| **Scroll and fixed element coexistence** | Add bottom/top content insets so lists are not hidden behind fixed bars | Scroll content obscured by sticky headers/footers |
+
+---
+
+## Pre-Delivery Checklist
+
+Before delivering UI code, verify these items:
+Scope notice: This checklist is for App UI (iOS/Android/React Native/Flutter).
+
+### Visual Quality
+- [ ] No emojis used as icons (use SVG instead)
+- [ ] All icons come from a consistent icon family and style
+- [ ] Official brand assets are used with correct proportions and clear space
+- [ ] Pressed-state visuals do not shift layout bounds or cause jitter
+- [ ] Semantic theme tokens are used consistently (no ad-hoc per-screen hardcoded colors)
+
+### Interaction
+- [ ] All tappable elements provide clear pressed feedback (ripple/opacity/elevation)
+- [ ] Touch targets meet minimum size (>=44x44pt iOS, >=48x48dp Android)
+- [ ] Micro-interaction timing stays in the 150-300ms range with native-feeling easing
+- [ ] Disabled states are visually clear and non-interactive
+- [ ] Screen reader focus order matches visual order, and interactive labels are descriptive
+- [ ] Gesture regions avoid nested/conflicting interactions (tap/drag/back-swipe conflicts)
+
+### Light/Dark Mode
+- [ ] Primary text contrast >=4.5:1 in both light and dark mode
+- [ ] Secondary text contrast >=3:1 in both light and dark mode
+- [ ] Dividers/borders and interaction states are distinguishable in both modes
+- [ ] Modal/drawer scrim opacity is strong enough to preserve foreground legibility (typically 40-60% black)
+- [ ] Both themes are tested before delivery (not inferred from a single theme)
+
+### Layout
+- [ ] Safe areas are respected for headers, tab bars, and bottom CTA bars
+- [ ] Scroll content is not hidden behind fixed/sticky bars
+- [ ] Verified on small phone, large phone, and tablet (portrait + landscape)
+- [ ] Horizontal insets/gutters adapt correctly by device size and orientation
+- [ ] 4/8dp spacing rhythm is maintained across component, section, and page levels
+- [ ] Long-form text measure remains readable on larger devices (no edge-to-edge paragraphs)
+
+### Accessibility
+- [ ] All meaningful images/icons have accessibility labels
+- [ ] Form fields have labels, hints, and clear error messages
+- [ ] Color is not the only indicator
+- [ ] Reduced motion and dynamic text size are supported without layout breakage
+- [ ] Accessibility traits/roles/states (selected, disabled, expanded) are announced correctly

App/frontend/.agent/skills/ui-ux-pro-max/data

@@ -0,0 +1 @@
+../../../src/ui-ux-pro-max/data

App/frontend/.agent/skills/ui-ux-pro-max/scripts

@@ -0,0 +1 @@
+../../../src/ui-ux-pro-max/scripts

App/frontend/.agents/skills/ui-ux-pro-max/SKILL.md

@@ -0,0 +1,659 @@
+---
+name: ui-ux-pro-max
+description: "UI/UX design intelligence for web and mobile. Includes 50+ styles, 161 color palettes, 57 font pairings, 161 product types, 99 UX guidelines, and 25 chart types across 10 stacks (React, Next.js, Vue, Svelte, SwiftUI, React Native, Flutter, Tailwind, shadcn/ui, and HTML/CSS). Actions: plan, build, create, design, implement, review, fix, improve, optimize, enhance, refactor, and check UI/UX code. Projects: website, landing page, dashboard, admin panel, e-commerce, SaaS, portfolio, blog, and mobile app. Elements: button, modal, navbar, sidebar, card, table, form, and chart. Styles: glassmorphism, claymorphism, minimalism, brutalism, neumorphism, bento grid, dark mode, responsive, skeuomorphism, and flat design. Topics: color systems, accessibility, animation, layout, typography, font pairing, spacing, interaction states, shadow, and gradient. Integrations: shadcn/ui MCP for component search and examples."
+---
+
+# UI/UX Pro Max - Design Intelligence
+
+Comprehensive design guide for web and mobile applications. Contains 50+ styles, 161 color palettes, 57 font pairings, 161 product types with reasoning rules, 99 UX guidelines, and 25 chart types across 10 technology stacks. Searchable database with priority-based recommendations.
+
+## When to Apply
+
+This Skill should be used when the task involves **UI structure, visual design decisions, interaction patterns, or user experience quality control**.
+
+### Must Use
+
+This Skill must be invoked in the following situations:
+
+- Designing new pages (Landing Page, Dashboard, Admin, SaaS, Mobile App)
+- Creating or refactoring UI components (buttons, modals, forms, tables, charts, etc.)
+- Choosing color schemes, typography systems, spacing standards, or layout systems
+- Reviewing UI code for user experience, accessibility, or visual consistency
+- Implementing navigation structures, animations, or responsive behavior
+- Making product-level design decisions (style, information hierarchy, brand expression)
+- Improving perceived quality, clarity, or usability of interfaces
+
+### Recommended
+
+This Skill is recommended in the following situations:
+
+- UI looks "not professional enough" but the reason is unclear
+- Receiving feedback on usability or experience
+- Pre-launch UI quality optimization
+- Aligning cross-platform design (Web / iOS / Android)
+- Building design systems or reusable component libraries
+
+### Skip
+
+This Skill is not needed in the following situations:
+
+- Pure backend logic development
+- Only involving API or database design
+- Performance optimization unrelated to the interface
+- Infrastructure or DevOps work
+- Non-visual scripts or automation tasks
+
+**Decision criteria**: If the task will change how a feature **looks, feels, moves, or is interacted with**, this Skill should be used.
+
+## Rule Categories by Priority
+
+*For human/AI reference: follow priority 1→10 to decide which rule category to focus on first; use `--domain <Domain>` to query details when needed. Scripts do not read this table.*
+
+| Priority | Category | Impact | Domain | Key Checks (Must Have) | Anti-Patterns (Avoid) |
+|----------|----------|--------|--------|------------------------|------------------------|
+| 1 | Accessibility | CRITICAL | `ux` | Contrast 4.5:1, Alt text, Keyboard nav, Aria-labels | Removing focus rings, Icon-only buttons without labels |
+| 2 | Touch & Interaction | CRITICAL | `ux` | Min size 44×44px, 8px+ spacing, Loading feedback | Reliance on hover only, Instant state changes (0ms) |
+| 3 | Performance | HIGH | `ux` | WebP/AVIF, Lazy loading, Reserve space (CLS &lt; 0.1) | Layout thrashing, Cumulative Layout Shift |
+| 4 | Style Selection | HIGH | `style`, `product` | Match product type, Consistency, SVG icons (no emoji) | Mixing flat & skeuomorphic randomly, Emoji as icons |
+| 5 | Layout & Responsive | HIGH | `ux` | Mobile-first breakpoints, Viewport meta, No horizontal scroll | Horizontal scroll, Fixed px container widths, Disable zoom |
+| 6 | Typography & Color | MEDIUM | `typography`, `color` | Base 16px, Line-height 1.5, Semantic color tokens | Text &lt; 12px body, Gray-on-gray, Raw hex in components |
+| 7 | Animation | MEDIUM | `ux` | Duration 150–300ms, Motion conveys meaning, Spatial continuity | Decorative-only animation, Animating width/height, No reduced-motion |
+| 8 | Forms & Feedback | MEDIUM | `ux` | Visible labels, Error near field, Helper text, Progressive disclosure | Placeholder-only label, Errors only at top, Overwhelm upfront |
+| 9 | Navigation Patterns | HIGH | `ux` | Predictable back, Bottom nav ≤5, Deep linking | Overloaded nav, Broken back behavior, No deep links |
+| 10 | Charts & Data | LOW | `chart` | Legends, Tooltips, Accessible colors | Relying on color alone to convey meaning |
+
+## Quick Reference
+
+### 1. Accessibility (CRITICAL)
+
+- `color-contrast` - Minimum 4.5:1 ratio for normal text (large text 3:1); Material Design
+- `focus-states` - Visible focus rings on interactive elements (2–4px; Apple HIG, MD)
+- `alt-text` - Descriptive alt text for meaningful images
+- `aria-labels` - aria-label for icon-only buttons; accessibilityLabel in native (Apple HIG)
+- `keyboard-nav` - Tab order matches visual order; full keyboard support (Apple HIG)
+- `form-labels` - Use label with for attribute
+- `skip-links` - Skip to main content for keyboard users
+- `heading-hierarchy` - Sequential h1→h6, no level skip
+- `color-not-only` - Don't convey info by color alone (add icon/text)
+- `dynamic-type` - Support system text scaling; avoid truncation as text grows (Apple Dynamic Type, MD)
+- `reduced-motion` - Respect prefers-reduced-motion; reduce/disable animations when requested (Apple Reduced Motion API, MD)
+- `voiceover-sr` - Meaningful accessibilityLabel/accessibilityHint; logical reading order for VoiceOver/screen readers (Apple HIG, MD)
+- `escape-routes` - Provide cancel/back in modals and multi-step flows (Apple HIG)
+- `keyboard-shortcuts` - Preserve system and a11y shortcuts; offer keyboard alternatives for drag-and-drop (Apple HIG)
+
+### 2. Touch & Interaction (CRITICAL)
+
+- `touch-target-size` - Min 44×44pt (Apple) / 48×48dp (Material); extend hit area beyond visual bounds if needed
+- `touch-spacing` - Minimum 8px/8dp gap between touch targets (Apple HIG, MD)
+- `hover-vs-tap` - Use click/tap for primary interactions; don't rely on hover alone
+- `loading-buttons` - Disable button during async operations; show spinner or progress
+- `error-feedback` - Clear error messages near problem
+- `cursor-pointer` - Add cursor-pointer to clickable elements (Web)
+- `gesture-conflicts` - Avoid horizontal swipe on main content; prefer vertical scroll
+- `tap-delay` - Use touch-action: manipulation to reduce 300ms delay (Web)
+- `standard-gestures` - Use platform standard gestures consistently; don't redefine (e.g. swipe-back, pinch-zoom) (Apple HIG)
+- `system-gestures` - Don't block system gestures (Control Center, back swipe, etc.) (Apple HIG)
+- `press-feedback` - Visual feedback on press (ripple/highlight; MD state layers)
+- `haptic-feedback` - Use haptic for confirmations and important actions; avoid overuse (Apple HIG)
+- `gesture-alternative` - Don't rely on gesture-only interactions; always provide visible controls for critical actions
+- `safe-area-awareness` - Keep primary touch targets away from notch, Dynamic Island, gesture bar and screen edges
+- `no-precision-required` - Avoid requiring pixel-perfect taps on small icons or thin edges
+- `swipe-clarity` - Swipe actions must show clear affordance or hint (chevron, label, tutorial)
+- `drag-threshold` - Use a movement threshold before starting drag to avoid accidental drags
+
+### 3. Performance (HIGH)
+
+- `image-optimization` - Use WebP/AVIF, responsive images (srcset/sizes), lazy load non-critical assets
+- `image-dimension` - Declare width/height or use aspect-ratio to prevent layout shift (Core Web Vitals: CLS)
+- `font-loading` - Use font-display: swap/optional to avoid invisible text (FOIT); reserve space to reduce layout shift (MD)
+- `font-preload` - Preload only critical fonts; avoid overusing preload on every variant
+- `critical-css` - Prioritize above-the-fold CSS (inline critical CSS or early-loaded stylesheet)
+- `lazy-loading` - Lazy load non-hero components via dynamic import / route-level splitting
+- `bundle-splitting` - Split code by route/feature (React Suspense / Next.js dynamic) to reduce initial load and TTI
+- `third-party-scripts` - Load third-party scripts async/defer; audit and remove unnecessary ones (MD)
+- `reduce-reflows` - Avoid frequent layout reads/writes; batch DOM reads then writes
+- `content-jumping` - Reserve space for async content to avoid layout jumps (Core Web Vitals: CLS)
+- `lazy-load-below-fold` - Use loading="lazy" for below-the-fold images and heavy media
+- `virtualize-lists` - Virtualize lists with 50+ items to improve memory efficiency and scroll performance
+- `main-thread-budget` - Keep per-frame work under ~16ms for 60fps; move heavy tasks off main thread (HIG, MD)
+- `progressive-loading` - Use skeleton screens / shimmer instead of long blocking spinners for >1s operations (Apple HIG)
+- `input-latency` - Keep input latency under ~100ms for taps/scrolls (Material responsiveness standard)
+- `tap-feedback-speed` - Provide visual feedback within 100ms of tap (Apple HIG)
+- `debounce-throttle` - Use debounce/throttle for high-frequency events (scroll, resize, input)
+- `offline-support` - Provide offline state messaging and basic fallback (PWA / mobile)
+- `network-fallback` - Offer degraded modes for slow networks (lower-res images, fewer animations)
+
+### 4. Style Selection (HIGH)
+
+- `style-match` - Match style to product type (use `--design-system` for recommendations)
+- `consistency` - Use same style across all pages
+- `no-emoji-icons` - Use SVG icons (Heroicons, Lucide), not emojis
+- `color-palette-from-product` - Choose palette from product/industry (search `--domain color`)
+- `effects-match-style` - Shadows, blur, radius aligned with chosen style (glass / flat / clay etc.)
+- `platform-adaptive` - Respect platform idioms (iOS HIG vs Material): navigation, controls, typography, motion
+- `state-clarity` - Make hover/pressed/disabled states visually distinct while staying on-style (Material state layers)
+- `elevation-consistent` - Use a consistent elevation/shadow scale for cards, sheets, modals; avoid random shadow values
+- `dark-mode-pairing` - Design light/dark variants together to keep brand, contrast, and style consistent
+- `icon-style-consistent` - Use one icon set/visual language (stroke width, corner radius) across the product
+- `system-controls` - Prefer native/system controls over fully custom ones; only customize when branding requires it (Apple HIG)
+- `blur-purpose` - Use blur to indicate background dismissal (modals, sheets), not as decoration (Apple HIG)
+- `primary-action` - Each screen should have only one primary CTA; secondary actions visually subordinate (Apple HIG)
+
+### 5. Layout & Responsive (HIGH)
+
+- `viewport-meta` - width=device-width initial-scale=1 (never disable zoom)
+- `mobile-first` - Design mobile-first, then scale up to tablet and desktop
+- `breakpoint-consistency` - Use systematic breakpoints (e.g. 375 / 768 / 1024 / 1440)
+- `readable-font-size` - Minimum 16px body text on mobile (avoids iOS auto-zoom)
+- `line-length-control` - Mobile 35–60 chars per line; desktop 60–75 chars
+- `horizontal-scroll` - No horizontal scroll on mobile; ensure content fits viewport width
+- `spacing-scale` - Use 4pt/8dp incremental spacing system (Material Design)
+- `touch-density` - Keep component spacing comfortable for touch: not cramped, not causing mis-taps
+- `container-width` - Consistent max-width on desktop (max-w-6xl / 7xl)
+- `z-index-management` - Define layered z-index scale (e.g. 0 / 10 / 20 / 40 / 100 / 1000)
+- `fixed-element-offset` - Fixed navbar/bottom bar must reserve safe padding for underlying content
+- `scroll-behavior` - Avoid nested scroll regions that interfere with the main scroll experience
+- `viewport-units` - Prefer min-h-dvh over 100vh on mobile
+- `orientation-support` - Keep layout readable and operable in landscape mode
+- `content-priority` - Show core content first on mobile; fold or hide secondary content
+- `visual-hierarchy` - Establish hierarchy via size, spacing, contrast — not color alone
+
+### 6. Typography & Color (MEDIUM)
+
+- `line-height` - Use 1.5-1.75 for body text
+- `line-length` - Limit to 65-75 characters per line
+- `font-pairing` - Match heading/body font personalities
+- `font-scale` - Consistent type scale (e.g. 12 14 16 18 24 32)
+- `contrast-readability` - Darker text on light backgrounds (e.g. slate-900 on white)
+- `text-styles-system` - Use platform type system: iOS 11 Dynamic Type styles / Material 5 type roles (display, headline, title, body, label) (HIG, MD)
+- `weight-hierarchy` - Use font-weight to reinforce hierarchy: Bold headings (600–700), Regular body (400), Medium labels (500) (MD)
+- `color-semantic` - Define semantic color tokens (primary, secondary, error, surface, on-surface) not raw hex in components (Material color system)
+- `color-dark-mode` - Dark mode uses desaturated / lighter tonal variants, not inverted colors; test contrast separately (HIG, MD)
+- `color-accessible-pairs` - Foreground/background pairs must meet 4.5:1 (AA) or 7:1 (AAA); use tools to verify (WCAG, MD)
+- `color-not-decorative-only` - Functional color (error red, success green) must include icon/text; avoid color-only meaning (HIG, MD)
+- `truncation-strategy` - Prefer wrapping over truncation; when truncating use ellipsis and provide full text via tooltip/expand (Apple HIG)
+- `letter-spacing` - Respect default letter-spacing per platform; avoid tight tracking on body text (HIG, MD)
+- `number-tabular` - Use tabular/monospaced figures for data columns, prices, and timers to prevent layout shift
+- `whitespace-balance` - Use whitespace intentionally to group related items and separate sections; avoid visual clutter (Apple HIG)
+
+### 7. Animation (MEDIUM)
+
+- `duration-timing` - Use 150–300ms for micro-interactions; complex transitions ≤400ms; avoid >500ms (MD)
+- `transform-performance` - Use transform/opacity only; avoid animating width/height/top/left
+- `loading-states` - Show skeleton or progress indicator when loading exceeds 300ms
+- `excessive-motion` - Animate 1-2 key elements per view max
+- `easing` - Use ease-out for entering, ease-in for exiting; avoid linear for UI transitions
+- `motion-meaning` - Every animation must express a cause-effect relationship, not just be decorative (Apple HIG)
+- `state-transition` - State changes (hover / active / expanded / collapsed / modal) should animate smoothly, not snap
+- `continuity` - Page/screen transitions should maintain spatial continuity (shared element, directional slide) (Apple HIG)
+- `parallax-subtle` - Use parallax sparingly; must respect reduced-motion and not cause disorientation (Apple HIG)
+- `spring-physics` - Prefer spring/physics-based curves over linear or cubic-bezier for natural feel (Apple HIG fluid animations)
+- `exit-faster-than-enter` - Exit animations shorter than enter (~60–70% of enter duration) to feel responsive (MD motion)
+- `stagger-sequence` - Stagger list/grid item entrance by 30–50ms per item; avoid all-at-once or too-slow reveals (MD)
+- `shared-element-transition` - Use shared element / hero transitions for visual continuity between screens (MD, HIG)
+- `interruptible` - Animations must be interruptible; user tap/gesture cancels in-progress animation immediately (Apple HIG)
+- `no-blocking-animation` - Never block user input during an animation; UI must stay interactive (Apple HIG)
+- `fade-crossfade` - Use crossfade for content replacement within the same container (MD)
+- `scale-feedback` - Subtle scale (0.95–1.05) on press for tappable cards/buttons; restore on release (HIG, MD)
+- `gesture-feedback` - Drag, swipe, and pinch must provide real-time visual response tracking the finger (MD Motion)
+- `hierarchy-motion` - Use translate/scale direction to express hierarchy: enter from below = deeper, exit upward = back (MD)
+- `motion-consistency` - Unify duration/easing tokens globally; all animations share the same rhythm and feel
+- `opacity-threshold` - Fading elements should not linger below opacity 0.2; either fade fully or remain visible
+- `modal-motion` - Modals/sheets should animate from their trigger source (scale+fade or slide-in) for spatial context (HIG, MD)
+- `navigation-direction` - Forward navigation animates left/up; backward animates right/down — keep direction logically consistent (HIG)
+- `layout-shift-avoid` - Animations must not cause layout reflow or CLS; use transform for position changes
+
+### 8. Forms & Feedback (MEDIUM)
+
+- `input-labels` - Visible label per input (not placeholder-only)
+- `error-placement` - Show error below the related field
+- `submit-feedback` - Loading then success/error state on submit
+- `required-indicators` - Mark required fields (e.g. asterisk)
+- `empty-states` - Helpful message and action when no content
+- `toast-dismiss` - Auto-dismiss toasts in 3-5s
+- `confirmation-dialogs` - Confirm before destructive actions
+- `input-helper-text` - Provide persistent helper text below complex inputs, not just placeholder (Material Design)
+- `disabled-states` - Disabled elements use reduced opacity (0.38–0.5) + cursor change + semantic attribute (MD)
+- `progressive-disclosure` - Reveal complex options progressively; don't overwhelm users upfront (Apple HIG)
+- `inline-validation` - Validate on blur (not keystroke); show error only after user finishes input (MD)
+- `input-type-keyboard` - Use semantic input types (email, tel, number) to trigger the correct mobile keyboard (HIG, MD)
+- `password-toggle` - Provide show/hide toggle for password fields (MD)
+- `autofill-support` - Use autocomplete / textContentType attributes so the system can autofill (HIG, MD)
+- `undo-support` - Allow undo for destructive or bulk actions (e.g. "Undo delete" toast) (Apple HIG)
+- `success-feedback` - Confirm completed actions with brief visual feedback (checkmark, toast, color flash) (MD)
+- `error-recovery` - Error messages must include a clear recovery path (retry, edit, help link) (HIG, MD)
+- `multi-step-progress` - Multi-step flows show step indicator or progress bar; allow back navigation (MD)
+- `form-autosave` - Long forms should auto-save drafts to prevent data loss on accidental dismissal (Apple HIG)
+- `sheet-dismiss-confirm` - Confirm before dismissing a sheet/modal with unsaved changes (Apple HIG)
+- `error-clarity` - Error messages must state cause + how to fix (not just "Invalid input") (HIG, MD)
+- `field-grouping` - Group related fields logically (fieldset/legend or visual grouping) (MD)
+- `read-only-distinction` - Read-only state should be visually and semantically different from disabled (MD)
+- `focus-management` - After submit error, auto-focus the first invalid field (WCAG, MD)
+- `error-summary` - For multiple errors, show summary at top with anchor links to each field (WCAG)
+- `touch-friendly-input` - Mobile input height ≥44px to meet touch target requirements (Apple HIG)
+- `destructive-emphasis` - Destructive actions use semantic danger color (red) and are visually separated from primary actions (HIG, MD)
+- `toast-accessibility` - Toasts must not steal focus; use aria-live="polite" for screen reader announcement (WCAG)
+- `aria-live-errors` - Form errors use aria-live region or role="alert" to notify screen readers (WCAG)
+- `contrast-feedback` - Error and success state colors must meet 4.5:1 contrast ratio (WCAG, MD)
+- `timeout-feedback` - Request timeout must show clear feedback with retry option (MD)
+
+### 9. Navigation Patterns (HIGH)
+
+- `bottom-nav-limit` - Bottom navigation max 5 items; use labels with icons (Material Design)
+- `drawer-usage` - Use drawer/sidebar for secondary navigation, not primary actions (Material Design)
+- `back-behavior` - Back navigation must be predictable and consistent; preserve scroll/state (Apple HIG, MD)
+- `deep-linking` - All key screens must be reachable via deep link / URL for sharing and notifications (Apple HIG, MD)
+- `tab-bar-ios` - iOS: use bottom Tab Bar for top-level navigation (Apple HIG)
+- `top-app-bar-android` - Android: use Top App Bar with navigation icon for primary structure (Material Design)
+- `nav-label-icon` - Navigation items must have both icon and text label; icon-only nav harms discoverability (MD)
+- `nav-state-active` - Current location must be visually highlighted (color, weight, indicator) in navigation (HIG, MD)
+- `nav-hierarchy` - Primary nav (tabs/bottom bar) vs secondary nav (drawer/settings) must be clearly separated (MD)
+- `modal-escape` - Modals and sheets must offer a clear close/dismiss affordance; swipe-down to dismiss on mobile (Apple HIG)
+- `search-accessible` - Search must be easily reachable (top bar or tab); provide recent/suggested queries (MD)
+- `breadcrumb-web` - Web: use breadcrumbs for 3+ level deep hierarchies to aid orientation (MD)
+- `state-preservation` - Navigating back must restore previous scroll position, filter state, and input (HIG, MD)
+- `gesture-nav-support` - Support system gesture navigation (iOS swipe-back, Android predictive back) without conflict (HIG, MD)
+- `tab-badge` - Use badges on nav items sparingly to indicate unread/pending; clear after user visits (HIG, MD)
+- `overflow-menu` - When actions exceed available space, use overflow/more menu instead of cramming (MD)
+- `bottom-nav-top-level` - Bottom nav is for top-level screens only; never nest sub-navigation inside it (MD)
+- `adaptive-navigation` - Large screens (≥1024px) prefer sidebar; small screens use bottom/top nav (Material Adaptive)
+- `back-stack-integrity` - Never silently reset the navigation stack or unexpectedly jump to home (HIG, MD)
+- `navigation-consistency` - Navigation placement must stay the same across all pages; don't change by page type
+- `avoid-mixed-patterns` - Don't mix Tab + Sidebar + Bottom Nav at the same hierarchy level
+- `modal-vs-navigation` - Modals must not be used for primary navigation flows; they break the user's path (HIG)
+- `focus-on-route-change` - After page transition, move focus to main content region for screen reader users (WCAG)
+- `persistent-nav` - Core navigation must remain reachable from deep pages; don't hide it entirely in sub-flows (HIG, MD)
+- `destructive-nav-separation` - Dangerous actions (delete account, logout) must be visually and spatially separated from normal nav items (HIG, MD)
+- `empty-nav-state` - When a nav destination is unavailable, explain why instead of silently hiding it (MD)
+
+### 10. Charts & Data (LOW)
+
+- `chart-type` - Match chart type to data type (trend → line, comparison → bar, proportion → pie/donut)
+- `color-guidance` - Use accessible color palettes; avoid red/green only pairs for colorblind users (WCAG, MD)
+- `data-table` - Provide table alternative for accessibility; charts alone are not screen-reader friendly (WCAG)
+- `pattern-texture` - Supplement color with patterns, textures, or shapes so data is distinguishable without color (WCAG, MD)
+- `legend-visible` - Always show legend; position near the chart, not detached below a scroll fold (MD)
+- `tooltip-on-interact` - Provide tooltips/data labels on hover (Web) or tap (mobile) showing exact values (HIG, MD)
+- `axis-labels` - Label axes with units and readable scale; avoid truncated or rotated labels on mobile
+- `responsive-chart` - Charts must reflow or simplify on small screens (e.g. horizontal bar instead of vertical, fewer ticks)
+- `empty-data-state` - Show meaningful empty state when no data exists ("No data yet" + guidance), not a blank chart (MD)
+- `loading-chart` - Use skeleton or shimmer placeholder while chart data loads; don't show an empty axis frame
+- `animation-optional` - Chart entrance animations must respect prefers-reduced-motion; data should be readable immediately (HIG)
+- `large-dataset` - For 1000+ data points, aggregate or sample; provide drill-down for detail instead of rendering all (MD)
+- `number-formatting` - Use locale-aware formatting for numbers, dates, currencies on axes and labels (HIG, MD)
+- `touch-target-chart` - Interactive chart elements (points, segments) must have ≥44pt tap area or expand on touch (Apple HIG)
+- `no-pie-overuse` - Avoid pie/donut for >5 categories; switch to bar chart for clarity
+- `contrast-data` - Data lines/bars vs background ≥3:1; data text labels ≥4.5:1 (WCAG)
+- `legend-interactive` - Legends should be clickable to toggle series visibility (MD)
+- `direct-labeling` - For small datasets, label values directly on the chart to reduce eye travel
+- `tooltip-keyboard` - Tooltip content must be keyboard-reachable and not rely on hover alone (WCAG)
+- `sortable-table` - Data tables must support sorting with aria-sort indicating current sort state (WCAG)
+- `axis-readability` - Axis ticks must not be cramped; maintain readable spacing, auto-skip on small screens
+- `data-density` - Limit information density per chart to avoid cognitive overload; split into multiple charts if needed
+- `trend-emphasis` - Emphasize data trends over decoration; avoid heavy gradients/shadows that obscure the data
+- `gridline-subtle` - Grid lines should be low-contrast (e.g. gray-200) so they don't compete with data
+- `focusable-elements` - Interactive chart elements (points, bars, slices) must be keyboard-navigable (WCAG)
+- `screen-reader-summary` - Provide a text summary or aria-label describing the chart's key insight for screen readers (WCAG)
+- `error-state-chart` - Data load failure must show error message with retry action, not a broken/empty chart
+- `export-option` - For data-heavy products, offer CSV/image export of chart data
+- `drill-down-consistency` - Drill-down interactions must maintain a clear back-path and hierarchy breadcrumb
+- `time-scale-clarity` - Time series charts must clearly label time granularity (day/week/month) and allow switching
+
+## How to Use
+
+Search specific domains using the CLI tool below.
+
+---
+
+## Prerequisites
+
+Check if Python is installed:
+
+```bash
+python3 --version || python --version
+```
+
+If Python is not installed, install it based on user's OS:
+
+**macOS:**
+```bash
+brew install python3
+```
+
+**Ubuntu/Debian:**
+```bash
+sudo apt update && sudo apt install python3
+```
+
+**Windows:**
+```powershell
+winget install Python.Python.3.12
+```
+
+---
+
+## How to Use This Skill
+
+Use this skill when the user requests any of the following:
+
+| Scenario | Trigger Examples | Start From |
+|----------|-----------------|------------|
+| **New project / page** | "Build a landing page", "Build a dashboard" | Step 1 → Step 2 (design system) |
+| **New component** | "Create a pricing card", "Add a modal" | Step 3 (domain search: style, ux) |
+| **Choose style / color / font** | "What style fits a fintech app?", "Recommend a color palette" | Step 2 (design system) |
+| **Review existing UI** | "Review this page for UX issues", "Check accessibility" | Quick Reference checklist above |
+| **Fix a UI bug** | "Button hover is broken", "Layout shifts on load" | Quick Reference → relevant section |
+| **Improve / optimize** | "Make this faster", "Improve mobile experience" | Step 3 (domain search: ux, react) |
+| **Implement dark mode** | "Add dark mode support" | Step 3 (domain: style "dark mode") |
+| **Add charts / data viz** | "Add an analytics dashboard chart" | Step 3 (domain: chart) |
+| **Stack best practices** | "React performance tips"、"SwiftUI navigation" | Step 4 (stack search) |
+
+Follow this workflow:
+
+### Step 1: Analyze User Requirements
+
+Extract key information from user request:
+- **Product type**: Entertainment (social, video, music, gaming), Tool (scanner, editor, converter), Productivity (task manager, notes, calendar), or hybrid
+- **Target audience**: C-end consumer users; consider age group, usage context (commute, leisure, work)
+- **Style keywords**: playful, vibrant, minimal, dark mode, content-first, immersive, etc.
+- **Stack**: React Native (this project's only tech stack)
+
+### Step 2: Generate Design System (REQUIRED)
+
+**Always start with `--design-system`** to get comprehensive recommendations with reasoning:
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "<product_type> <industry> <keywords>" --design-system [-p "Project Name"]
+```
+
+This command:
+1. Searches domains in parallel (product, style, color, landing, typography)
+2. Applies reasoning rules from `ui-reasoning.csv` to select best matches
+3. Returns complete design system: pattern, style, colors, typography, effects
+4. Includes anti-patterns to avoid
+
+**Example:**
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "beauty spa wellness service" --design-system -p "Serenity Spa"
+```
+
+### Step 2b: Persist Design System (Master + Overrides Pattern)
+
+To save the design system for **hierarchical retrieval across sessions**, add `--persist`:
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Project Name"
+```
+
+This creates:
+- `design-system/MASTER.md` — Global Source of Truth with all design rules
+- `design-system/pages/` — Folder for page-specific overrides
+
+**With page-specific override:**
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "<query>" --design-system --persist -p "Project Name" --page "dashboard"
+```
+
+This also creates:
+- `design-system/pages/dashboard.md` — Page-specific deviations from Master
+
+**How hierarchical retrieval works:**
+1. When building a specific page (e.g., "Checkout"), first check `design-system/pages/checkout.md`
+2. If the page file exists, its rules **override** the Master file
+3. If not, use `design-system/MASTER.md` exclusively
+
+**Context-aware retrieval prompt:**
+```
+I am building the [Page Name] page. Please read design-system/MASTER.md.
+Also check if design-system/pages/[page-name].md exists.
+If the page file exists, prioritize its rules.
+If not, use the Master rules exclusively.
+Now, generate the code...
+```
+
+### Step 3: Supplement with Detailed Searches (as needed)
+
+After getting the design system, use domain searches to get additional details:
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "<keyword>" --domain <domain> [-n <max_results>]
+```
+
+**When to use detailed searches:**
+
+| Need | Domain | Example |
+|------|--------|---------|
+| Product type patterns | `product` | `--domain product "entertainment social"` |
+| More style options | `style` | `--domain style "glassmorphism dark"` |
+| Color palettes | `color` | `--domain color "entertainment vibrant"` |
+| Font pairings | `typography` | `--domain typography "playful modern"` |
+| Chart recommendations | `chart` | `--domain chart "real-time dashboard"` |
+| UX best practices | `ux` | `--domain ux "animation accessibility"` |
+| Alternative fonts | `typography` | `--domain typography "elegant luxury"` |
+| Individual Google Fonts | `google-fonts` | `--domain google-fonts "sans serif popular variable"` |
+| Landing structure | `landing` | `--domain landing "hero social-proof"` |
+| React Native perf | `react` | `--domain react "rerender memo list"` |
+| App interface a11y | `web` | `--domain web "accessibilityLabel touch safe-areas"` |
+| AI prompt / CSS keywords | `prompt` | `--domain prompt "minimalism"` |
+
+### Step 4: Stack Guidelines (React Native)
+
+Get React Native implementation-specific best practices:
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "<keyword>" --stack react-native
+```
+
+---
+
+## Search Reference
+
+### Available Domains
+
+| Domain | Use For | Example Keywords |
+|--------|---------|------------------|
+| `product` | Product type recommendations | SaaS, e-commerce, portfolio, healthcare, beauty, service |
+| `style` | UI styles, colors, effects | glassmorphism, minimalism, dark mode, brutalism |
+| `typography` | Font pairings, Google Fonts | elegant, playful, professional, modern |
+| `color` | Color palettes by product type | saas, ecommerce, healthcare, beauty, fintech, service |
+| `landing` | Page structure, CTA strategies | hero, hero-centric, testimonial, pricing, social-proof |
+| `chart` | Chart types, library recommendations | trend, comparison, timeline, funnel, pie |
+| `ux` | Best practices, anti-patterns | animation, accessibility, z-index, loading |
+| `google-fonts` | Individual Google Fonts lookup | sans serif, monospace, japanese, variable font, popular |
+| `react` | React/Next.js performance | waterfall, bundle, suspense, memo, rerender, cache |
+| `web` | App interface guidelines (iOS/Android/React Native) | accessibilityLabel, touch targets, safe areas, Dynamic Type |
+| `prompt` | AI prompts, CSS keywords | (style name) |
+
+### Available Stacks
+
+| Stack | Focus |
+|-------|-------|
+| `react-native` | Components, Navigation, Lists |
+
+---
+
+## Example Workflow
+
+**User request:** "Make an AI search homepage."
+
+### Step 1: Analyze Requirements
+- Product type: Tool (AI search engine)
+- Target audience: C-end users looking for fast, intelligent search
+- Style keywords: modern, minimal, content-first, dark mode
+- Stack: React Native
+
+### Step 2: Generate Design System (REQUIRED)
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "AI search tool modern minimal" --design-system -p "AI Search"
+```
+
+**Output:** Complete design system with pattern, style, colors, typography, effects, and anti-patterns.
+
+### Step 3: Supplement with Detailed Searches (as needed)
+
+```bash
+# Get style options for a modern tool product
+python3 skills/ui-ux-pro-max/scripts/search.py "minimalism dark mode" --domain style
+
+# Get UX best practices for search interaction and loading
+python3 skills/ui-ux-pro-max/scripts/search.py "search loading animation" --domain ux
+```
+
+### Step 4: Stack Guidelines
+
+```bash
+python3 skills/ui-ux-pro-max/scripts/search.py "list performance navigation" --stack react-native
+```
+
+**Then:** Synthesize design system + detailed searches and implement the design.
+
+---
+
+## Output Formats
+
+The `--design-system` flag supports two output formats:
+
+```bash
+# ASCII box (default) - best for terminal display
+python3 skills/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system
+
+# Markdown - best for documentation
+python3 skills/ui-ux-pro-max/scripts/search.py "fintech crypto" --design-system -f markdown
+```
+
+---
+
+## Tips for Better Results
+
+### Query Strategy
+
+- Use **multi-dimensional keywords** — combine product + industry + tone + density: `"entertainment social vibrant content-dense"` not just `"app"`
+- Try different keywords for the same need: `"playful neon"` → `"vibrant dark"` → `"content-first minimal"`
+- Use `--design-system` first for full recommendations, then `--domain` to deep-dive any dimension you're unsure about
+- Always add `--stack react-native` for implementation-specific guidance
+
+### Common Sticking Points
+
+| Problem | What to Do |
+|---------|------------|
+| Can't decide on style/color | Re-run `--design-system` with different keywords |
+| Dark mode contrast issues | Quick Reference §6: `color-dark-mode` + `color-accessible-pairs` |
+| Animations feel unnatural | Quick Reference §7: `spring-physics` + `easing` + `exit-faster-than-enter` |
+| Form UX is poor | Quick Reference §8: `inline-validation` + `error-clarity` + `focus-management` |
+| Navigation feels confusing | Quick Reference §9: `nav-hierarchy` + `bottom-nav-limit` + `back-behavior` |
+| Layout breaks on small screens | Quick Reference §5: `mobile-first` + `breakpoint-consistency` |
+| Performance / jank | Quick Reference §3: `virtualize-lists` + `main-thread-budget` + `debounce-throttle` |
+
+### Pre-Delivery Checklist
+
+- Run `--domain ux "animation accessibility z-index loading"` as a UX validation pass before implementation
+- Run through Quick Reference **§1–§3** (CRITICAL + HIGH) as a final review
+- Test on 375px (small phone) and landscape orientation
+- Verify behavior with **reduced-motion** enabled and **Dynamic Type** at largest size
+- Check dark mode contrast independently (don't assume light mode values work)
+- Confirm all touch targets ≥44pt and no content hidden behind safe areas
+
+---
+
+## Common Rules for Professional UI
+
+These are frequently overlooked issues that make UI look unprofessional:
+Scope notice: The rules below are for App UI (iOS/Android/React Native/Flutter), not desktop-web interaction patterns.
+
+### Icons & Visual Elements
+
+| Rule | Standard | Avoid | Why It Matters |
+|------|----------|--------|----------------|
+| **No Emoji as Structural Icons** | Use vector-based icons (e.g., Lucide, react-native-vector-icons, @expo/vector-icons). | Using emojis (🎨 🚀 ⚙️) for navigation, settings, or system controls. | Emojis are font-dependent, inconsistent across platforms, and cannot be controlled via design tokens. |
+| **Vector-Only Assets** | Use SVG or platform vector icons that scale cleanly and support theming. | Raster PNG icons that blur or pixelate. | Ensures scalability, crisp rendering, and dark/light mode adaptability. |
+| **Stable Interaction States** | Use color, opacity, or elevation transitions for press states without changing layout bounds. | Layout-shifting transforms that move surrounding content or trigger visual jitter. | Prevents unstable interactions and preserves smooth motion/perceived quality on mobile. |
+| **Correct Brand Logos** | Use official brand assets and follow their usage guidelines (spacing, color, clear space). | Guessing logo paths, recoloring unofficially, or modifying proportions. | Prevents brand misuse and ensures legal/platform compliance. |
+| **Consistent Icon Sizing** | Define icon sizes as design tokens (e.g., icon-sm, icon-md = 24pt, icon-lg). | Mixing arbitrary values like 20pt / 24pt / 28pt randomly. | Maintains rhythm and visual hierarchy across the interface. |
+| **Stroke Consistency** | Use a consistent stroke width within the same visual layer (e.g., 1.5px or 2px). | Mixing thick and thin stroke styles arbitrarily. | Inconsistent strokes reduce perceived polish and cohesion. |
+| **Filled vs Outline Discipline** | Use one icon style per hierarchy level. | Mixing filled and outline icons at the same hierarchy level. | Maintains semantic clarity and stylistic coherence. |
+| **Touch Target Minimum** | Minimum 44×44pt interactive area (use hitSlop if icon is smaller). | Small icons without expanded tap area. | Meets accessibility and platform usability standards. |
+| **Icon Alignment** | Align icons to text baseline and maintain consistent padding. | Misaligned icons or inconsistent spacing around them. | Prevents subtle visual imbalance that reduces perceived quality. |
+| **Icon Contrast** | Follow WCAG contrast standards: 4.5:1 for small elements, 3:1 minimum for larger UI glyphs. | Low-contrast icons that blend into the background. | Ensures accessibility in both light and dark modes. |
+
+
+### Interaction (App)
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **Tap feedback** | Provide clear pressed feedback (ripple/opacity/elevation) within 80-150ms | No visual response on tap |
+| **Animation timing** | Keep micro-interactions around 150-300ms with platform-native easing | Instant transitions or slow animations (>500ms) |
+| **Accessibility focus** | Ensure screen reader focus order matches visual order and labels are descriptive | Unlabeled controls or confusing focus traversal |
+| **Disabled state clarity** | Use disabled semantics (`disabled`/native disabled props), reduced emphasis, and no tap action | Controls that look tappable but do nothing |
+| **Touch target minimum** | Keep tap areas >=44x44pt (iOS) or >=48x48dp (Android), expand hit area when icon is smaller | Tiny tap targets or icon-only hit areas without padding |
+| **Gesture conflict prevention** | Keep one primary gesture per region and avoid nested tap/drag conflicts | Overlapping gestures causing accidental actions |
+| **Semantic native controls** | Prefer native interactive primitives (`Button`, `Pressable`, platform equivalents) with proper accessibility roles | Generic containers used as primary controls without semantics |
+
+### Light/Dark Mode Contrast
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **Surface readability (light)** | Keep cards/surfaces clearly separated from background with sufficient opacity/elevation | Overly transparent surfaces that blur hierarchy |
+| **Text contrast (light)** | Maintain body text contrast >=4.5:1 against light surfaces | Low-contrast gray body text |
+| **Text contrast (dark)** | Maintain primary text contrast >=4.5:1 and secondary text >=3:1 on dark surfaces | Dark mode text that blends into background |
+| **Border and divider visibility** | Ensure separators are visible in both themes (not just light mode) | Theme-specific borders disappearing in one mode |
+| **State contrast parity** | Keep pressed/focused/disabled states equally distinguishable in light and dark themes | Defining interaction states for one theme only |
+| **Token-driven theming** | Use semantic color tokens mapped per theme across app surfaces/text/icons | Hardcoded per-screen hex values |
+| **Scrim and modal legibility** | Use a modal scrim strong enough to isolate foreground content (typically 40-60% black) | Weak scrim that leaves background visually competing |
+
+### Layout & Spacing
+
+| Rule | Do | Don't |
+|------|----|----- |
+| **Safe-area compliance** | Respect top/bottom safe areas for all fixed headers, tab bars, and CTA bars | Placing fixed UI under notch, status bar, or gesture area |
+| **System bar clearance** | Add spacing for status/navigation bars and gesture home indicator | Let tappable content collide with OS chrome |
+| **Consistent content width** | Keep predictable content width per device class (phone/tablet) | Mixing arbitrary widths between screens |
+| **8dp spacing rhythm** | Use a consistent 4/8dp spacing system for padding/gaps/section spacing | Random spacing increments with no rhythm |
+| **Readable text measure** | Keep long-form text readable on large devices (avoid edge-to-edge paragraphs on tablets) | Full-width long text that hurts readability |
+| **Section spacing hierarchy** | Define clear vertical rhythm tiers (e.g., 16/24/32/48) by hierarchy | Similar UI levels with inconsistent spacing |
+| **Adaptive gutters by breakpoint** | Increase horizontal insets on larger widths and in landscape | Same narrow gutter on all device sizes/orientations |
+| **Scroll and fixed element coexistence** | Add bottom/top content insets so lists are not hidden behind fixed bars | Scroll content obscured by sticky headers/footers |
+
+---
+
+## Pre-Delivery Checklist
+
+Before delivering UI code, verify these items:
+Scope notice: This checklist is for App UI (iOS/Android/React Native/Flutter).
+
+### Visual Quality
+- [ ] No emojis used as icons (use SVG instead)
+- [ ] All icons come from a consistent icon family and style
+- [ ] Official brand assets are used with correct proportions and clear space
+- [ ] Pressed-state visuals do not shift layout bounds or cause jitter
+- [ ] Semantic theme tokens are used consistently (no ad-hoc per-screen hardcoded colors)
+
+### Interaction
+- [ ] All tappable elements provide clear pressed feedback (ripple/opacity/elevation)
+- [ ] Touch targets meet minimum size (>=44x44pt iOS, >=48x48dp Android)
+- [ ] Micro-interaction timing stays in the 150-300ms range with native-feeling easing
+- [ ] Disabled states are visually clear and non-interactive
+- [ ] Screen reader focus order matches visual order, and interactive labels are descriptive
+- [ ] Gesture regions avoid nested/conflicting interactions (tap/drag/back-swipe conflicts)
+
+### Light/Dark Mode
+- [ ] Primary text contrast >=4.5:1 in both light and dark mode
+- [ ] Secondary text contrast >=3:1 in both light and dark mode
+- [ ] Dividers/borders and interaction states are distinguishable in both modes
+- [ ] Modal/drawer scrim opacity is strong enough to preserve foreground legibility (typically 40-60% black)
+- [ ] Both themes are tested before delivery (not inferred from a single theme)
+
+### Layout
+- [ ] Safe areas are respected for headers, tab bars, and bottom CTA bars
+- [ ] Scroll content is not hidden behind fixed/sticky bars
+- [ ] Verified on small phone, large phone, and tablet (portrait + landscape)
+- [ ] Horizontal insets/gutters adapt correctly by device size and orientation
+- [ ] 4/8dp spacing rhythm is maintained across component, section, and page levels
+- [ ] Long-form text measure remains readable on larger devices (no edge-to-edge paragraphs)
+
+### Accessibility
+- [ ] All meaningful images/icons have accessibility labels
+- [ ] Form fields have labels, hints, and clear error messages
+- [ ] Color is not the only indicator
+- [ ] Reduced motion and dynamic text size are supported without layout breakage
+- [ ] Accessibility traits/roles/states (selected, disabled, expanded) are announced correctly

App/frontend/.agents/skills/ui-ux-pro-max/data

@@ -0,0 +1 @@
+../../../src/ui-ux-pro-max/data

App/frontend/.agents/skills/ui-ux-pro-max/scripts

@@ -0,0 +1 @@
+../../../src/ui-ux-pro-max/scripts

App/frontend/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

App/frontend/README.md

@@ -0,0 +1,16 @@
+# React + Vite
+
+This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules.
+
+Currently, two official plugins are available:
+
+- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Babel](https://babeljs.io/) (or [oxc](https://oxc.rs) when used in [rolldown-vite](https://vite.dev/guide/rolldown)) for Fast Refresh
+- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh
+
+## React Compiler
+
+The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+
+## Expanding the ESLint configuration
+
+If you are developing a production application, we recommend using TypeScript with type-aware lint rules enabled. Check out the [TS template](https://github.com/vitejs/vite/tree/main/packages/create-vite/template-react-ts) for information on how to integrate TypeScript and [`typescript-eslint`](https://typescript-eslint.io) in your project.

App/frontend/eslint.config.js

@@ -0,0 +1,29 @@
+import js from '@eslint/js'
+import globals from 'globals'
+import reactHooks from 'eslint-plugin-react-hooks'
+import reactRefresh from 'eslint-plugin-react-refresh'
+import { defineConfig, globalIgnores } from 'eslint/config'
+
+export default defineConfig([
+  globalIgnores(['dist']),
+  {
+    files: ['**/*.{js,jsx}'],
+    extends: [
+      js.configs.recommended,
+      reactHooks.configs.flat.recommended,
+      reactRefresh.configs.vite,
+    ],
+    languageOptions: {
+      ecmaVersion: 2020,
+      globals: globals.browser,
+      parserOptions: {
+        ecmaVersion: 'latest',
+        ecmaFeatures: { jsx: true },
+        sourceType: 'module',
+      },
+    },
+    rules: {
+      'no-unused-vars': ['error', { varsIgnorePattern: '^[A-Z_]' }],
+    },
+  },
+])

App/frontend/index.html

@@ -0,0 +1,25 @@
+<!doctype html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8" />
+  <link rel="icon" type="image/png" href="/logo.png" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <meta name="theme-color" content="#ffffff" />
+  <meta name="description" content="An offline-first e-reader experience" />
+  <title>E-Reader</title>
+  <!-- Prevent theme flash: apply saved theme before React renders -->
+  <script>
+    (function () {
+      var t = localStorage.getItem('theme') || 'dark';
+      document.documentElement.setAttribute('data-theme', t);
+    })();
+  </script>
+</head>
+
+<body>
+  <div id="root"></div>
+  <script type="module" src="/src/main.jsx"></script>
+</body>
+
+</html>

App/frontend/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "frontend",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "lint": "eslint .",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "epubjs": "^0.3.93",
+    "localforage": "^1.10.0",
+    "lucide-react": "^0.575.0",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.1",
+    "eslint": "^9.39.1",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.4.24",
+    "globals": "^16.5.0",
+    "vite": "^7.3.1",
+    "vite-plugin-pwa": "^1.2.0"
+  }
+}

App/frontend/skills-lock.json

@@ -0,0 +1,10 @@
+{
+  "version": 1,
+  "skills": {
+    "ui-ux-pro-max": {
+      "source": "nextlevelbuilder/ui-ux-pro-max-skill",
+      "sourceType": "github",
+      "computedHash": "6337038fe1fe6bbe1b9f252ab678ee575859190bab6f0f246f4061824eb40875"
+    }
+  }
+}

App/frontend/src/App.css

@@ -0,0 +1,42 @@
+#root {
+  max-width: 1280px;
+  margin: 0 auto;
+  padding: 2rem;
+  text-align: center;
+}
+
+.logo {
+  height: 6em;
+  padding: 1.5em;
+  will-change: filter;
+  transition: filter 300ms;
+}
+.logo:hover {
+  filter: drop-shadow(0 0 2em #646cffaa);
+}
+.logo.react:hover {
+  filter: drop-shadow(0 0 2em #61dafbaa);
+}
+
+@keyframes logo-spin {
+  from {
+    transform: rotate(0deg);
+  }
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  a:nth-of-type(2) .logo {
+    animation: logo-spin infinite 20s linear;
+  }
+}
+
+.card {
+  padding: 2em;
+}
+
+.read-the-docs {
+  color: #888;
+}

App/frontend/src/App.jsx

@@ -0,0 +1,755 @@
+import React, { useState, useEffect, useRef, useMemo, useCallback } from 'react';
+import ePub from 'epubjs';
+import localforage from 'localforage';
+import { 
+  Play, Pause, SkipBack, SkipForward, FileText, Upload, 
+  Settings, Search, BookOpen, ChevronLeft, Type, 
+  Trash2, List, Bookmark, ChevronDown 
+} from 'lucide-react';
+
+/* ─── PWA ─── */
+import { useRegisterSW } from 'virtual:pwa-register/react';
+
+/* ─── Components ─── */
+import Sidebar from './components/Sidebar';
+import SettingsPanel from './components/SettingsPanel';
+import ReaderParagraph from './components/ReaderParagraph';
+import AudioDock from './components/AudioDock';
+import TOCPopover from './components/TOCPopover';
+import BookmarksPopover from './components/BookmarksPopover';
+
+/* ─── Utils ─── */
+import { 
+  splitTextIntoChunks, 
+  extractChunksFromEpubDoc, 
+  calculateReadingTime 
+} from './utils/epubHelpers';
+import './index.css';
+
+// Worker instance
+const parsingWorker = new Worker(new URL('./workers/parsingWorker.js', import.meta.url));
+
+// Configure storage
+localforage.config({ name: 'E-Reader', storeName: 'library' });
+
+function App() {
+  const [view, setView] = useState('library');
+  const [books, setBooks] = useState([]);
+  const [libraryLoaded, setLibraryLoaded] = useState(false);
+  const [activeBookIndex, setActiveBookIndex] = useState(null);
+  const [chunks, setChunks] = useState([]);
+  const [currentChunkIndex, setCurrentChunkIndex] = useState(0);
+  const [isPlaying, setIsPlaying] = useState(false);
+  const [loadingAudio, setLoadingAudio] = useState(false);
+  const [audioCache, setAudioCache] = useState({}); // { index: { url } }
+  const [serverReady, setServerReady] = useState(false);
+
+  // User Preferences
+  const [theme, setTheme] = useState(() => localStorage.getItem('theme') || 'auto');
+  const [speechRate, setSpeechRate] = useState(1.0);
+  const [piperVoice, setPiperVoice] = useState('en_US-lessac-low');
+  const [piperSpeaker, setPiperSpeaker] = useState(0);
+  const [readingFont, setReadingFont] = useState(() => localStorage.getItem('readingFont') || 'serif');
+  const [readingSpacing, setReadingSpacing] = useState(() => localStorage.getItem('readingSpacing') || 'normal');
+  const [highlightColor, setHighlightColor] = useState(() => localStorage.getItem('highlightColor') || '#fcff82');
+
+  // UI States
+  const [showSettings, setShowSettings] = useState(false);
+  const [showTOC, setShowTOC] = useState(false);
+  const [showBookmarks, setShowBookmarks] = useState(false);
+  const [showSortMenu, setShowSortMenu] = useState(false);
+  const [librarySearchQuery, setLibrarySearchQuery] = useState('');
+  const [librarySortOption, setLibrarySortOption] = useState('recently-read');
+
+  // Handle outside clicks for menus
+  useEffect(() => {
+    const handleOutsideClick = (e) => {
+      if (!e.target.closest('.sort-dropdown-container')) {
+        setShowSortMenu(false);
+      }
+    };
+    window.addEventListener('click', handleOutsideClick);
+    return () => window.removeEventListener('click', handleOutsideClick);
+  }, []);
+
+  // Refs
+  const audioRef = useRef(new Audio());
+  const fileInputRef = useRef(null);
+  const activeParagraphRef = useRef(null);
+  const searchInputRef = useRef(null);
+  const viewRef = useRef(view);
+  const isPlayingRef = useRef(isPlaying);
+  const lastSavedBooksRef = useRef(null);
+
+  useEffect(() => { viewRef.current = view; }, [view]);
+  useEffect(() => { isPlayingRef.current = isPlaying; }, [isPlaying]);
+
+  // Initial Load
+  useEffect(() => {
+    let mounts = true;
+    async function init() {
+      try {
+        const [savedBooks, savedRate, savedVoice, savedSpeaker] = await Promise.all([
+          localforage.getItem('books'),
+          localStorage.getItem('speechRate'),
+          localStorage.getItem('piperVoice'),
+          localStorage.getItem('piperSpeaker')
+        ]);
+        if (mounts) {
+          if (savedBooks) setBooks(savedBooks);
+          if (savedRate) setSpeechRate(parseFloat(savedRate));
+          if (savedVoice) setPiperVoice(savedVoice);
+          if (savedSpeaker) setPiperSpeaker(parseInt(savedSpeaker));
+          setLibraryLoaded(true);
+        }
+      } catch (e) { console.error(e); }
+    }
+    init();
+    return () => { mounts = false; };
+  }, []);
+
+  // Warm up the backend immediately so it's ready when user presses Play
+  useEffect(() => {
+    const apiUrl = import.meta.env.VITE_API_URL || '';
+    fetch(`${apiUrl}/warmup`)
+      .then(() => setServerReady(true))
+      .catch(() => setServerReady(true)); // Don't block UI even if warmup fails
+  }, []);
+
+  // Sync to Storage
+  useEffect(() => {
+    if (libraryLoaded && books !== lastSavedBooksRef.current) {
+      const timeout = setTimeout(() => {
+        localforage.setItem('books', books).catch(e => console.error(e));
+        lastSavedBooksRef.current = books;
+      }, 2000);
+      return () => clearTimeout(timeout);
+    }
+  }, [books, libraryLoaded]);
+
+  // Handle Position Update
+  useEffect(() => {
+    if (activeBookIndex !== null && libraryLoaded && books[activeBookIndex]) {
+      setBooks(prev => {
+        if (prev[activeBookIndex].lastPosition === currentChunkIndex) return prev;
+        const nb = [...prev];
+        nb[activeBookIndex] = { ...nb[activeBookIndex], lastPosition: currentChunkIndex };
+        return nb;
+      });
+    }
+  }, [currentChunkIndex]);
+
+  // Global Styles
+  useEffect(() => {
+    const applyTheme = (t) => {
+      if (t === 'auto') {
+        const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+        document.documentElement.setAttribute('data-theme', prefersDark ? 'dark' : 'light');
+      } else {
+        document.documentElement.setAttribute('data-theme', t);
+      }
+    };
+    applyTheme(theme);
+    localStorage.setItem('theme', theme);
+  }, [theme]);
+
+  useEffect(() => {
+    const fontMap = {
+      serif: "'Playfair Display', Georgia, serif",
+      sans: "'Instrument Sans', system-ui, sans-serif",
+      georgia: "Georgia, 'Times New Roman', serif",
+      mono: "'Courier New', Courier, monospace"
+    };
+    document.documentElement.style.setProperty('--reader-font', fontMap[readingFont] || fontMap.serif);
+    localStorage.setItem('readingFont', readingFont);
+  }, [readingFont]);
+
+  useEffect(() => {
+    document.documentElement.style.setProperty('--highlight-color', highlightColor);
+    localStorage.setItem('highlightColor', highlightColor);
+  }, [highlightColor]);
+
+  useEffect(() => {
+    const spacingMap = {
+      compact: { lh: '1.6', ls: '-0.01em', ps: '1.2rem' },
+      normal: { lh: '2.0', ls: '0em', ps: '1.85rem' },
+      relaxed: { lh: '2.4', ls: '0.01em', ps: '2.4rem' },
+      spacious: { lh: '2.8', ls: '0.02em', ps: '3rem' }
+    };
+    const s = spacingMap[readingSpacing] || spacingMap.normal;
+    document.documentElement.style.setProperty('--reader-line-height', s.lh);
+    document.documentElement.style.setProperty('--reader-letter-spacing', s.ls);
+    document.documentElement.style.setProperty('--reader-para-spacing', s.ps);
+    localStorage.setItem('readingSpacing', readingSpacing);
+  }, [readingSpacing]);
+
+  // Playback Logic
+  const prefetchNextChunks = async (currentIndex) => {
+    const PREFETCH_COUNT = 2;
+    const apiUrl = import.meta.env.VITE_API_URL || '';
+    
+    for (let i = 1; i <= PREFETCH_COUNT; i++) {
+      const idx = currentIndex + i;
+      if (idx >= chunks.length || audioCache[idx]) continue;
+
+      const chunk = chunks[idx];
+      const text = typeof chunk === 'string' ? chunk : chunk.text;
+      
+      // Fire and forget fetch
+      fetch(`${apiUrl}/synthesize`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ text, voice_id: piperVoice, speaker_id: piperSpeaker })
+      }).then(async (resp) => {
+        if (resp.ok) {
+          const blob = await resp.blob();
+          const url = URL.createObjectURL(blob);
+          setAudioCache(prev => ({ ...prev, [idx]: { url, blob } }));
+        }
+      }).catch(err => console.error("Prefetch error:", err));
+    }
+  };
+
+  const playCurrentChunk = async () => {
+    const chunk = chunks[currentChunkIndex];
+    if (!chunk) return;
+    const text = typeof chunk === 'string' ? chunk : chunk.text;
+
+    audioRef.current.pause();
+
+    // Check Cache first
+    if (audioCache[currentChunkIndex]) {
+      const { url } = audioCache[currentChunkIndex];
+      if (viewRef.current === 'reader' && isPlayingRef.current) {
+        audioRef.current.src = url;
+        audioRef.current.playbackRate = speechRate;
+        await audioRef.current.play();
+        prefetchNextChunks(currentChunkIndex); // Always try to keep buffer full
+      }
+      return;
+    }
+
+    setLoadingAudio(true);
+    try {
+      const apiUrl = import.meta.env.VITE_API_URL || '';
+      const resp = await fetch(`${apiUrl}/synthesize`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ text, voice_id: piperVoice, speaker_id: piperSpeaker })
+      });
+      if (!resp.ok) throw new Error("Synthesis failed");
+      const blob = await resp.blob();
+      const url = URL.createObjectURL(blob);
+      
+      // Save to cache
+      setAudioCache(prev => ({ ...prev, [currentChunkIndex]: { url, blob } }));
+
+      if (viewRef.current === 'reader' && isPlayingRef.current) {
+        audioRef.current.src = url;
+        audioRef.current.playbackRate = speechRate;
+        await audioRef.current.play();
+        prefetchNextChunks(currentChunkIndex);
+      }
+    } catch (err) { console.error(err); setIsPlaying(false); }
+    finally { setLoadingAudio(false); }
+  };
+
+  const goToNextChunk = useCallback(() => {
+    setCurrentChunkIndex(prev => {
+      if (prev < chunks.length - 1) return prev + 1;
+      setIsPlaying(false);
+      return prev;
+    });
+  }, [chunks.length]);
+
+  useEffect(() => {
+    const audio = audioRef.current;
+    const handled = () => goToNextChunk();
+    audio.addEventListener('ended', handled);
+    return () => audio.removeEventListener('ended', handled);
+  }, [goToNextChunk]);
+
+  useEffect(() => {
+    audioRef.current.playbackRate = speechRate;
+  }, [speechRate]);
+
+  useEffect(() => {
+    if (isPlaying && chunks.length > 0) {
+      playCurrentChunk();
+      // Redirect to active paragraph when starting playback
+      if (activeParagraphRef.current) {
+        activeParagraphRef.current.scrollIntoView({ behavior: 'smooth', block: 'center' });
+      }
+    }
+  }, [isPlaying]);
+
+  useEffect(() => {
+    if (isPlaying && chunks.length > 0) {
+      playCurrentChunk();
+    }
+    // Auto-scroll to active paragraph on chunk change
+    if (activeParagraphRef.current) {
+      activeParagraphRef.current.scrollIntoView({ behavior: 'smooth', block: 'center' });
+    }
+  }, [currentChunkIndex]);
+
+  const handlePlayPause = () => {
+    if (chunks.length === 0) return;
+    if (isPlaying) {
+      setIsPlaying(false);
+      audioRef.current.pause();
+    } else {
+      setIsPlaying(true);
+      // The useEffect on currentChunkIndex will handle playCurrentChunk()
+      // but only if currentChunkIndex actually changed. We call it here manually
+      // if it's the first time playing or a resume.
+      if (!audioRef.current.src || audioRef.current.src === '' || audioRef.current.ended) {
+        playCurrentChunk();
+      } else {
+        audioRef.current.play().catch(() => playCurrentChunk());
+      }
+    }
+  };
+
+  const handleParagraphClick = useCallback((idx) => {
+    if (idx === currentChunkIndex) {
+      handlePlayPause();
+    } else {
+      setCurrentChunkIndex(idx);
+      if (!isPlaying) setIsPlaying(true);
+    }
+  }, [isPlaying, currentChunkIndex]);
+
+  // Actions
+  const openBook = (idx) => {
+    const ub = [...books];
+    ub[idx] = { ...ub[idx], lastOpened: Date.now() };
+    setBooks(ub);
+    
+    setActiveBookIndex(idx);
+    setChunks(ub[idx].chunks);
+    setAudioCache({}); // Clear cache for new book
+    setCurrentChunkIndex(ub[idx].lastPosition || 0);
+    setIsPlaying(false);
+    audioRef.current.pause();
+    setView('reader');
+  };
+
+  const removeBook = (e, idx) => {
+    e.stopPropagation();
+    setBooks(prev => prev.filter((_, i) => i !== idx));
+  };
+
+  const toggleBookmark = () => {
+    if (activeBookIndex === null) return;
+    const ub = [...books];
+    const b = ub[activeBookIndex];
+    if (!b.bookmarks) b.bookmarks = [];
+    const existing = b.bookmarks.findIndex(x => x.chunkIndex === currentChunkIndex);
+    if (existing !== -1) {
+      b.bookmarks.splice(existing, 1);
+    } else {
+      let preview = '';
+      if (chunks[currentChunkIndex]) {
+        const t = typeof chunks[currentChunkIndex] === 'string' ? chunks[currentChunkIndex] : chunks[currentChunkIndex].text;
+        preview = t.substring(0, 45) + '...';
+      }
+      b.bookmarks.push({ chunkIndex: currentChunkIndex, timestamp: Date.now(), preview });
+      b.bookmarks.sort((a, b) => a.chunkIndex - b.chunkIndex);
+    }
+    setBooks(ub);
+  };
+
+  // PWA Registration
+  const {
+    offlineReady: [offlineReady, setOfflineReady],
+    needRefresh: [needRefresh, setNeedRefresh],
+    updateServiceWorker,
+  } = useRegisterSW();
+
+  useEffect(() => {
+    localStorage.setItem('piperVoice', piperVoice);
+    localStorage.setItem('piperSpeaker', piperSpeaker.toString());
+    localStorage.setItem('speechRate', speechRate.toString());
+    
+    // Clear cache if voice settings change significantly
+    setAudioCache({});
+    
+    // Auto-re-play if voice changes while reading
+    if (isPlaying && chunks.length > 0) {
+      playCurrentChunk();
+    }
+  }, [piperVoice, piperSpeaker, speechRate]);
+
+  // Handle Worker Response
+  useEffect(() => {
+    parsingWorker.onmessage = (e) => {
+      if (e.data.type === 'PARSE_COMPLETE') {
+        const { segments, chunks: txtChunks, title } = e.data;
+        
+        setBooks(prev => {
+          const updated = [...prev];
+          if (!updated[0] || !updated[0].isParsing) return prev;
+
+          let finalChunks = [];
+          if (segments) {
+            // EPUB: Calculate start index for each spine segment
+            let currentOffset = 0;
+            const segmentStarts = segments.map(seg => {
+              const start = currentOffset;
+              currentOffset += seg.length;
+              return start;
+            });
+
+            finalChunks = segments.flat();
+
+            // Link TOC to chunks using spineIndex
+            const toc = updated[0].toc || [];
+            const mappedTOC = toc.map(item => ({
+              ...item,
+              chunkIndex: segmentStarts[item.spineIndex] || 0
+            }));
+
+            updated[0] = { ...updated[0], chunks: finalChunks, toc: mappedTOC, isParsing: false };
+          } else {
+            // TXT logic
+            updated[0] = { ...updated[0], chunks: txtChunks, isParsing: false, title: title || updated[0].title };
+          }
+          return updated;
+        });
+      }
+    };
+  }, []);
+
+  // EPUB Upload
+  const handleFileUpload = async (e) => {
+    const file = e.target.files[0];
+    if (!file) return;
+
+    const placeholderId = Date.now().toString();
+    const nb = { 
+      id: placeholderId, title: file.name.replace(/\.[^/.]+$/, ""), author: "Parsing...", chunks: [], isParsing: true,
+      lastPosition: 0, lastOpened: Date.now(), coverBase64: null, toc: [], bookmarks: [] 
+    };
+    setBooks(prev => [nb, ...prev]);
+
+    if (file.name.endsWith('.txt')) {
+      const text = await file.text();
+      parsingWorker.postMessage({ type: 'PARSE_TXT', content: text, fileName: file.name });
+    } else if (file.name.endsWith('.epub')) {
+      const book = ePub(file);
+      await book.ready;
+      let coverBase64 = null, toc = [], extractedTitle = "", extractedAuthor = "", spinePaths = [];
+      try {
+        const metadata = await book.loaded.metadata;
+        extractedTitle = metadata.title;
+        extractedAuthor = metadata.creator;
+        const cu = await book.coverUrl();
+        if (cu) {
+          const resp = await fetch(cu);
+          const blob = await resp.blob();
+          coverBase64 = await new Promise(r => {
+            const fr = new FileReader();
+            fr.onloadend = () => r(fr.result);
+            fr.readAsDataURL(blob);
+          });
+        }
+        const nav = await book.loaded.navigation;
+        const flattoc = (items) => {
+          items.forEach(item => {
+            // Aggressive spine matching for robust TOC mapping
+            const cleanHref = item.href.split('#')[0];
+            let spineIndex = -1;
+            
+            // Try Epubjs native get
+            const nativeMatch = book.spine.get(item.href);
+            if (nativeMatch) {
+              spineIndex = nativeMatch.index;
+            } else {
+              // Fallback to searching spine items by partial path
+              spineIndex = book.spine.spineItems.findIndex(si => 
+                si.href === cleanHref || 
+                si.href.endsWith('/' + cleanHref) || 
+                cleanHref.endsWith('/' + si.href)
+              );
+            }
+
+            toc.push({ 
+              label: item.label.trim(), 
+              href: item.href, 
+              spineIndex: spineIndex >= 0 ? spineIndex : 0 
+            });
+            if (item.subitems) flattoc(item.subitems);
+          });
+        };
+        flattoc(nav.toc || []);
+
+        const spineSegments = [];
+        for (const item of book.spine.spineItems) {
+          spinePaths.push(item.href);
+          const doc = await book.load(item.href);
+          spineSegments.push(doc.body.innerHTML);
+        }
+        
+        setBooks(prev => {
+          const u = [...prev];
+          if (u[0] && u[0].id === placeholderId) {
+            u[0] = { ...u[0], title: extractedTitle, author: extractedAuthor, coverBase64, toc, spinePaths };
+          }
+          return u;
+        });
+
+        parsingWorker.postMessage({ type: 'PARSE_HTML_SEGMENTS', content: spineSegments });
+      } catch (err) { console.error(err); }
+    }
+  };
+
+  // Keyboard Shortcuts
+  useEffect(() => {
+    const handleKD = (e) => {
+      if (document.activeElement.tagName === 'INPUT') return;
+      if (e.key === ' ' && view === 'reader') { e.preventDefault(); handlePlayPause(); }
+      if (e.key === 'ArrowRight' && view === 'reader') setCurrentChunkIndex(p => Math.min(chunks.length - 1, p + 1));
+      if (e.key === 'ArrowLeft' && view === 'reader') setCurrentChunkIndex(p => Math.max(0, p - 1));
+      if (e.key === '/' && view === 'library') { e.preventDefault(); searchInputRef.current?.focus(); }
+    };
+    window.addEventListener('keydown', handleKD);
+    return () => window.removeEventListener('keydown', handleKD);
+  }, [view, chunks.length, isPlaying]);
+
+  // Memoized lists
+  const filteredBooks = useMemo(() => {
+    let list = books.map((b, i) => ({ ...b, originalIndex: i }))
+      .filter(b => (b.title + b.author).toLowerCase().includes(librarySearchQuery.toLowerCase()));
+    if (librarySortOption === 'recently-read') list.sort((a,b) => (b.lastOpened||0) - (a.lastOpened||0));
+    else if (librarySortOption === 'title-asc') list.sort((a,b) => (a.title||'').localeCompare(b.title||''));
+    return list;
+  }, [books, librarySearchQuery, librarySortOption]);
+
+  const activeBook = activeBookIndex !== null ? books[activeBookIndex] : null;
+
+  if (!libraryLoaded) return <div className="loading-screen"><div className="spinner"/></div>;
+
+  return (
+    <div className="app-container">
+      {view === 'library' && (
+        <React.Fragment>
+          <Sidebar
+            view={view} setView={setView} activeBook={activeBook}
+            onLogoClick={() => { setView('library'); audioRef.current.pause(); setIsPlaying(false); }}
+            searchQuery={librarySearchQuery} onSearchChange={e => setLibrarySearchQuery(e.target.value)} searchRef={searchInputRef}
+            piperVoice={piperVoice} onVoiceChange={e => setPiperVoice(e.target.value)}
+            speechRate={speechRate} onRateChange={e => setSpeechRate(parseFloat(e.target.value))}
+            showSettings={showSettings} setShowSettings={setShowSettings}
+          />
+          <main className="main-content page-enter">
+            <header className="header" style={{ padding: '0 3.5rem' }}>
+              <div className="header-title">Library</div>
+              <div className="header-actions">
+                {!serverReady && (
+                  <span style={{ fontSize: '11px', color: 'var(--text-muted)', letterSpacing: '0.05em', display: 'flex', alignItems: 'center', gap: '6px', marginRight: '1rem' }}>
+                    <span style={{ width: 6, height: 6, borderRadius: '50%', background: '#f59e0b', display: 'inline-block', animation: 'pulse 1.5s infinite' }} />
+                    Connecting to voice server…
+                  </span>
+                )}
+                <span className="book-count">
+                  {books.length} {books.length === 1 ? 'BOOK' : 'BOOKS'}
+                </span>
+                
+                <div style={{ position: 'relative' }} className="sort-dropdown-container">
+                  <button 
+                    className={`btn-text ${showSortMenu ? 'active' : ''}`} 
+                    onClick={(e) => { e.stopPropagation(); setShowSortMenu(!showSortMenu); }}
+                    aria-label="Change Sort Order"
+                    title="Change Sort Order"
+                    style={{ marginRight: '1rem' }}
+                  >
+                    {librarySortOption === 'recently-read' ? "Recently Read" : "Alphabetical (A-Z)"}
+                    <ChevronDown size={14} style={{ marginLeft: '6px', opacity: 0.5 }} />
+                  </button>
+                  
+                  {showSortMenu && (
+                    <div 
+                      className="dropdown-menu glass" 
+                      style={{ position: 'absolute', top: 'calc(100% + 8px)', right: 0, zIndex: 100, minWidth: '180px', padding: '0.5rem', animation: 'dropdownEnter 0.2s ease-out' }}
+                      onClick={e => e.stopPropagation()}
+                    >
+                      <button 
+                        className={`dropdown-item ${librarySortOption === 'recently-read' ? 'active' : ''}`}
+                        onClick={() => { setLibrarySortOption('recently-read'); setShowSortMenu(false); }}
+                      >
+                        Recently Read
+                      </button>
+                      <button 
+                        className={`dropdown-item ${librarySortOption === 'title-asc' ? 'active' : ''}`}
+                        onClick={() => { setLibrarySortOption('title-asc'); setShowSortMenu(false); }}
+                      >
+                        Alphabetical (A-Z)
+                      </button>
+                    </div>
+                  )}
+                </div>
+
+                <button className="btn-text" onClick={() => fileInputRef.current?.click()}><Upload size={14}/> Import</button>
+                <input type="file" ref={fileInputRef} onChange={handleFileUpload} style={{ display: 'none' }} accept=".txt,.epub" />
+              </div>
+            </header>
+            
+            {filteredBooks.length === 0 ? (
+              <div className="empty-library">
+                <BookOpen size={48} style={{ marginBottom: '1.5rem', color: 'var(--text-muted)' }} />
+                <h3 style={{ marginBottom: '0.5rem', fontFamily: 'var(--font-display)', fontStyle: 'italic', fontSize: '1.5rem' }}>Your Library is Empty</h3>
+                <p style={{ color: 'var(--text-secondary)', maxWidth: '300px', textAlign: 'center' }}>
+                  Import EPUB or TXT files to start reading and listening.
+                </p>
+              </div>
+            ) : (
+              <div className="library-grid">
+                {filteredBooks.map(book => {
+                  const progressPct = book.chunks.length > 0 ? Math.floor(((book.lastPosition || 0) / book.chunks.length) * 100) : 0;
+                  const remainingChunks = book.chunks.length - (book.lastPosition || 0);
+                  const remainingTime = calculateReadingTime(remainingChunks, speechRate);
+                  
+                  return (
+                    <div 
+                      key={book.id} 
+                      className={`book-card ${book.isParsing ? 'is-parsing' : ''}`} 
+                      onClick={() => !book.isParsing && openBook(book.originalIndex)}
+                    >
+                      <div className="book-cover" style={{ backgroundImage: book.coverBase64 ? `url(${book.coverBase64})` : 'none', backgroundSize: 'cover', backgroundPosition: 'center' }}>
+                        {!book.coverBase64 && (
+                          <div className="book-cover-content">
+                            <span className="default-cover-title">{book.title}</span>
+                            <span className="default-cover-author">{book.author || "Unknown Author"}</span>
+                          </div>
+                        )}
+                        {book.isParsing && (
+                          <div className="parsing-overlay">
+                            <div className="spinner-small" />
+                          </div>
+                        )}
+                        <button 
+                        className="delete-book-btn" 
+                        onClick={e => removeBook(e, book.originalIndex)}
+                        aria-label="Remove Book"
+                        title="Remove Book"
+                      >
+                        <Trash2 size={18} />
+                      </button>
+                      </div>
+                      <div className="book-title">{book.title}</div>
+                      <div className="book-author">{book.author}</div>
+                      
+                      {!book.isParsing && book.chunks.length > 0 && (
+                        <div className="book-progress-container">
+                          <div className="book-progress-labels">
+                            <span>{progressPct}%</span>
+                            <span>{remainingTime} left</span>
+                          </div>
+                          <div className="book-progress-track">
+                            <div className="book-progress-fill" style={{ width: `${progressPct}%` }} />
+                          </div>
+                        </div>
+                      )}
+                    </div>
+                  );
+                })}
+              </div>
+            )}
+          </main>
+        </React.Fragment>
+      )}
+
+      {view === 'reader' && activeBook && (
+        <div className="reader-wrapper page-enter">
+          <header className="reader-header" style={{ position: 'relative' }}>
+            <div style={{ display: 'flex', width: '100%', height: '100%', alignItems: 'center', justifyContent: 'space-between', padding: '0 1.5rem' }}>
+              <button className="btn-icon" style={{ gap: '6px', color: 'var(--text-primary)', width: 'auto', padding: '0.5rem 0.75rem' }} onClick={() => { setView('library'); setIsPlaying(false); audioRef.current.pause(); }}>
+                <ChevronLeft size={20} /> <span style={{ fontSize: '14px', fontWeight: 600 }}>Library</span>
+              </button>
+              <div style={{ position: 'absolute', left: '50%', transform: 'translateX(-50%)', textAlign: 'center', pointerEvents: 'none', fontFamily: 'var(--font-display)', fontStyle: 'italic', fontSize: '1rem', color: 'var(--text-secondary)', letterSpacing: '0.01em', maxWidth: '320px', overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
+                {activeBook.title}
+              </div>
+              <div style={{ display: 'flex', gap: '16px', alignItems: 'center' }}>
+                <button 
+                  className="btn-icon" 
+                  onClick={toggleBookmark}
+                  title="Bookmark current paragraph"
+                  style={{ color: activeBook.bookmarks?.some(x => x.chunkIndex === currentChunkIndex) ? 'var(--highlight-color)' : 'inherit' }}
+                >
+                  <Bookmark size={18} fill={activeBook.bookmarks?.some(x => x.chunkIndex === currentChunkIndex) ? 'currentColor' : 'none'} />
+                </button>
+                  <button 
+                    className={`btn-icon ${showBookmarks ? 'active' : ''}`} 
+                    onClick={() => { setShowBookmarks(!showBookmarks); setShowTOC(false); setShowSettings(false); }}
+                    title="View bookmarks list"
+                    aria-label="View bookmarks list"
+                  >
+                    <Bookmark size={18} />
+                  </button>
+                  <button 
+                    className={`btn-icon ${showTOC ? 'active' : ''}`} 
+                    onClick={() => { setShowTOC(!showTOC); setShowSettings(false); setShowBookmarks(false); }}
+                    title="Table of Contents"
+                    aria-label="Table of Contents"
+                  >
+                    <List size={18} />
+                  </button>
+                  <button 
+                    className={`btn-icon ${showSettings ? 'active' : ''}`} 
+                    onClick={() => { setShowSettings(!showSettings); setShowTOC(false); setShowBookmarks(false); }}
+                    title="Display settings"
+                    aria-label="Display settings"
+                  >
+                    <Type size={18} />
+                  </button>
+              </div>
+            </div>
+            {/* Enhanced progress bar at bottom of reader header */}
+            <div style={{ position: 'absolute', bottom: -1, left: 0, width: '100%', height: '2px', background: 'var(--border-color)', zIndex: 11 }}>
+              <div style={{ height: '100%', background: 'var(--highlight-color)', width: `${Math.floor((currentChunkIndex / (chunks.length || 1)) * 100)}%`, transition: 'width 0.3s ease', boxShadow: '0 0 10px var(--highlight-color)' }} />
+            </div>
+          </header>
+
+          {showSettings && (
+            <SettingsPanel
+              readingFont={readingFont} setReadingFont={setReadingFont}
+              readingSpacing={readingSpacing} setReadingSpacing={setReadingSpacing}
+              theme={theme} setTheme={setTheme}
+              highlightColor={highlightColor} setHighlightColor={setHighlightColor}
+              piperVoice={piperVoice} handleVoiceChange={e => setPiperVoice(e.target.value)}
+              piperSpeaker={piperSpeaker} handleSpeakerChange={e => setPiperSpeaker(parseInt(e.target.value))}
+              speechRate={speechRate} handleRateChange={e => setSpeechRate(parseFloat(e.target.value))}
+              onClose={() => setShowSettings(false)}
+            />
+          )}
+          {showTOC && <TOCPopover toc={activeBook.toc} currentChunkIndex={currentChunkIndex} onJump={setCurrentChunkIndex} onClose={() => setShowTOC(false)} />}
+          {showBookmarks && <BookmarksPopover bookmarks={activeBook.bookmarks} onJump={setCurrentChunkIndex} onClose={() => setShowBookmarks(false)} />}
+
+          <div className="reader-content" onClick={() => { setShowSettings(false); setShowTOC(false); setShowBookmarks(false); }}>
+            <div className="book-page">
+              {chunks.map((c, i) => (
+                <ReaderParagraph key={i} chunk={c} index={i} isActive={i === currentChunkIndex} activeParagraphRef={activeParagraphRef} onClick={handleParagraphClick} />
+              ))}
+            </div>
+          </div>
+
+          <AudioDock
+            activeBook={activeBook} currentChunkIndex={currentChunkIndex} chunks={chunks}
+            isPlaying={isPlaying} loadingAudio={loadingAudio}
+            onPlayPause={handlePlayPause}
+            onSkipBack={() => setCurrentChunkIndex(p => Math.max(0, p-1))}
+            onSkipForward={() => setCurrentChunkIndex(p => Math.min(chunks.length-1, p+1))}
+            onProgressClick={(e) => {
+              const rect = e.currentTarget.getBoundingClientRect();
+              const pct = (e.clientX - rect.left) / rect.width;
+              setCurrentChunkIndex(Math.floor(pct * chunks.length));
+            }}
+          />
+        </div>
+      )}
+    </div>
+  );
+}
+
+export default App;

App/frontend/src/components/AudioDock.jsx

@@ -0,0 +1,56 @@
+import React from 'react';
+import { Play, Pause, SkipBack, SkipForward } from 'lucide-react';
+
+export default function AudioDock({
+  activeBook,
+  currentChunkIndex,
+  chunks,
+  isPlaying,
+  loadingAudio,
+  onPlayPause,
+  onSkipBack,
+  onSkipForward,
+  onProgressClick
+}) {
+  if (!activeBook) return null;
+
+  return (
+    <div className="audio-dock">
+      <div className="dock-controls">
+        <button className="dock-btn" onClick={onSkipBack}>
+          <SkipBack size={18} fill="currentColor" />
+        </button>
+
+        <button className="dock-btn play" onClick={onPlayPause} disabled={chunks.length === 0}>
+          {loadingAudio ? (
+            <div className="spinner" />
+          ) : (
+            isPlaying ? <Pause size={18} fill="currentColor" /> : <Play size={18} fill="currentColor" style={{ marginLeft: '2px' }} />
+          )}
+        </button>
+
+        <button className="dock-btn" onClick={onSkipForward}>
+          <SkipForward size={18} fill="currentColor" />
+        </button>
+      </div>
+
+      <div className="dock-info">
+        <div style={{ display: 'flex', justifyContent: 'space-between', alignItems: 'baseline' }}>
+          <div className="dock-title">{activeBook.title}</div>
+          <div className="dock-subtitle">Powered by Piper</div>
+        </div>
+
+        <div className="dock-progress">
+          <span>Page {chunks.length > 0 ? Math.floor(currentChunkIndex / 15) + 1 : 0}</span>
+          <div className="scrubber" onClick={onProgressClick}>
+            <div
+              className="scrubber-fill"
+              style={{ width: `${chunks.length > 0 ? (currentChunkIndex / chunks.length) * 100 : 0}%` }}
+            />
+          </div>
+          <span>{chunks.length > 0 ? Math.floor(chunks.length / 15) + 1 : 0}</span>
+        </div>
+      </div>
+    </div>
+  );
+}

App/frontend/src/components/BookmarksPopover.jsx

@@ -0,0 +1,31 @@
+import React from 'react';
+import { BookOpen } from 'lucide-react';
+
+export default function BookmarksPopover({ bookmarks, onJump, onClose }) {
+  return (
+    <div className="bookmarks-popover">
+      <div className="settings-section-title" style={{ padding: '0 8px', marginBottom: '12px' }}>Bookmarks</div>
+      <div className="toc-list">
+        {(bookmarks?.length || 0) === 0 ? (
+          <div style={{ padding: '8px', fontSize: '14px', color: 'var(--text-muted)' }}>
+            No bookmarks yet.
+          </div>
+        ) : (
+          bookmarks.map((bm, i) => (
+            <div
+              key={`bm-${i}`}
+              className="toc-item"
+              onClick={() => { onJump(bm.chunkIndex); onClose(); }}
+              style={{ display: 'flex', alignItems: 'center', gap: '8px' }}
+            >
+              <BookOpen size={14} style={{ flexShrink: 0, color: 'var(--highlight-color)' }} />
+              <div style={{ flex: 1, overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
+                Page {Math.floor(bm.chunkIndex / 15) + 1}: {bm.preview}
+              </div>
+            </div>
+          ))
+        )}
+      </div>
+    </div>
+  );
+}

App/frontend/src/components/EReaderLogo.jsx

@@ -0,0 +1,34 @@
+import React from 'react';
+
+export default function EReaderLogo({ onClick }) {
+  return (
+    <svg
+      viewBox="0 0 168 38"
+      height="34"
+      aria-label="eReader."
+      role="img"
+      onClick={onClick}
+      style={{
+        cursor: 'pointer',
+        display: 'block',
+        marginBottom: '2rem',
+        paddingLeft: '0.25rem',
+        color: 'var(--text-primary)',
+        flexShrink: 0,
+      }}
+    >
+      <text
+        x="2"
+        y="30"
+        fontFamily="'Playfair Display', Georgia, serif"
+        fontStyle="italic"
+        fontWeight="700"
+        fontSize="32"
+        fill="currentColor"
+        letterSpacing="-0.5"
+      >
+        eReader.
+      </text>
+    </svg>
+  );
+}

App/frontend/src/components/ReaderParagraph.jsx

@@ -0,0 +1,31 @@
+import React from 'react';
+
+const ReaderParagraph = React.memo(({ chunk, index, isActive, activeParagraphRef, onClick }) => {
+  const text = typeof chunk === 'string' ? chunk : chunk.text;
+  const type = typeof chunk === 'string' ? 'p' : (chunk.type || 'p');
+  const isHeading = ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'].includes(type);
+  const Tag = isHeading ? type : 'p';
+
+  return (
+    <Tag
+      data-chunk-index={index}
+      ref={isActive ? activeParagraphRef : null}
+      onClick={() => onClick(index)}
+      className={`reader-paragraph ${isActive ? 'active' : ''}`}
+      style={isActive ? {
+        backgroundColor: 'var(--highlight-color)',
+        color: '#000000',
+        borderRadius: '6px',
+        padding: '0.4rem 0.75rem',
+        marginLeft: '-0.75rem',
+        marginRight: '-0.75rem',
+        boxShadow: '0 0 0 6px var(--highlight-color)',
+        transition: 'background-color 0.3s ease, box-shadow 0.3s ease'
+      } : {}}
+    >
+      {text}
+    </Tag>
+  );
+});
+
+export default ReaderParagraph;

App/frontend/src/components/SettingsPanel.jsx

@@ -0,0 +1,150 @@
+import React from 'react';
+
+export default function SettingsPanel({
+  readingFont, setReadingFont,
+  readingSpacing, setReadingSpacing,
+  theme, setTheme,
+  highlightColor, setHighlightColor,
+  piperVoice, handleVoiceChange,
+  piperSpeaker, handleSpeakerChange,
+  speechRate, handleRateChange,
+  onClose
+}) {
+  const spacingSteps = ['compact', 'normal', 'relaxed', 'spacious'];
+  const spacingIdx = spacingSteps.indexOf(readingSpacing);
+
+  return (
+    <div className="settings-popover">
+      {/* Panel header */}
+      <div className="sp-header">
+        <span className="sp-title">Display & Voice</span>
+        <button className="btn-icon sp-close" onClick={onClose} aria-label="Close settings">
+          <svg width="14" height="14" viewBox="0 0 14 14" fill="none"><path d="M1 1l12 12M13 1L1 13" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round"/></svg>
+        </button>
+      </div>
+
+      {/* ── Typography ── */}
+      <div className="sp-group">
+        <span className="sp-group-label">Typography</span>
+
+        {/* Font Select */}
+        <div className="sp-row sp-row-col">
+          <span className="sp-row-label">Typeface</span>
+          <select
+            className="sp-select sp-font-select"
+            value={readingFont}
+            onChange={e => setReadingFont(e.target.value)}
+          >
+            <option value="serif">Playfair Display — Serif</option>
+            <option value="sans">Instrument Sans — Humanist</option>
+            <option value="georgia">Georgia — Old Style</option>
+            <option value="mono">Courier New — Monospace</option>
+          </select>
+        </div>
+
+        {/* Spacing Steps */}
+        <div className="sp-row sp-row-col">
+          <div className="sp-label-between">
+            <span className="sp-row-label">Spacing</span>
+            <span className="sp-step-badge">{readingSpacing}</span>
+          </div>
+          <div className="sp-step-wrap">
+            <input
+              type="range" min="0" max="3" step="1"
+              value={spacingIdx}
+              onChange={e => setReadingSpacing(spacingSteps[+e.target.value])}
+              className="sp-range sp-range-stepped"
+            />
+            <div className="sp-step-ticks">
+              {spacingSteps.map((s, i) => (
+                <span
+                  key={s}
+                  className={`sp-tick ${i === spacingIdx ? 'active' : ''}`}
+                  onClick={() => setReadingSpacing(s)}
+                >
+                  {s[0].toUpperCase()}
+                </span>
+              ))}
+            </div>
+          </div>
+        </div>
+      </div>
+
+      {/* ── Appearance ── */}
+      <div className="sp-group">
+        <span className="sp-group-label">Appearance</span>
+        <div className="sp-theme-row">
+          {[
+            { value: 'auto',  icon: <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M12 3a9 9 0 1 0 0 18 9 9 0 0 0 0-18z"/><path d="M12 3v18"/><path d="M12 3c4.97 0 9 4.03 9 9s-4.03 9-9 9"/></svg>, label: 'Auto'  },
+            { value: 'light', icon: <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><circle cx="12" cy="12" r="5"/><path d="M12 1v2M12 21v2M4.22 4.22l1.42 1.42M18.36 18.36l1.42 1.42M1 12h2M21 12h2M4.22 19.78l1.42-1.42M18.36 5.64l1.42-1.42"/></svg>, label: 'Light' },
+            { value: 'dark',  icon: <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/></svg>, label: 'Dark'  },
+          ].map(opt => (
+            <button
+              key={opt.value}
+              className={`sp-theme-btn ${theme === opt.value ? 'active' : ''}`}
+              onClick={() => setTheme(opt.value)}
+            >
+              {opt.icon}
+              <span>{opt.label}</span>
+            </button>
+          ))}
+        </div>
+      </div>
+
+      {/* ── Highlight color ── */}
+      <div className="sp-group">
+        <span className="sp-group-label">Highlight</span>
+        <div className="sp-color-row">
+          {['#fcff82', '#a5d8ff', '#b2f2bb', '#ffc9c9', '#eebefa', '#ffffff'].map(color => (
+            <button
+              key={color}
+              className={`sp-color-btn ${highlightColor === color ? 'active' : ''}`}
+              onClick={() => setHighlightColor(color)}
+              style={{ '--swatch-bg': color }}
+              aria-label={`Highlight color ${color}`}
+            />
+          ))}
+        </div>
+      </div>
+
+      {/* ── Playback ── */}
+      <div className="sp-group">
+        <span className="sp-group-label">Playback</span>
+        <div className="sp-row sp-row-col">
+          <span className="sp-row-label">Voice</span>
+          <select value={piperVoice} onChange={handleVoiceChange} className="sp-select">
+            <option disabled style={{ fontWeight: 600 }}>🇺🇸 US English</option>
+            <option value="en_US-lessac-medium">Lessac — Female</option>
+            <option value="en_US-joe-medium">Joe — Male</option>
+            <option value="en_US-libritts_r-medium">LibriTTS — Multi</option>
+            <option disabled style={{ fontWeight: 600 }}>🇬🇧 British English</option>
+            <option value="en_GB-alan-medium">Alan — Male</option>
+            <option value="en_GB-northern_english_male-medium">Northern Male</option>
+            <option value="en_GB-semaine-medium">Semaine</option>
+            <option value="en_GB-southern_english_female-low">Southern Female</option>
+          </select>
+          {piperVoice === 'en_US-libritts_r-medium' && (
+            <input
+              type="number" min="0" max="903"
+              value={piperSpeaker}
+              onChange={handleSpeakerChange}
+              placeholder="Speaker ID (0–903)"
+              className="sp-number"
+            />
+          )}
+        </div>
+        <div className="sp-row">
+          <span className="sp-row-label">Speed</span>
+          <div className="sp-slider-wrap">
+            <input
+              type="range" min="0.5" max="2.0" step="0.1"
+              value={speechRate} onChange={handleRateChange}
+              className="sp-range"
+            />
+            <span className="sp-range-val">{speechRate}×</span>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}

App/frontend/src/components/Sidebar.jsx

@@ -0,0 +1,80 @@
+import React from 'react';
+import { Search, FileText, BookOpen, Settings } from 'lucide-react';
+import EReaderLogo from './EReaderLogo';
+
+export default function Sidebar({
+  view, setView, activeBook, onLogoClick, searchQuery, onSearchChange, searchRef,
+  piperVoice, onVoiceChange, speechRate, onRateChange, showSettings, setShowSettings
+}) {
+  return (
+    <aside className="sidebar glass">
+      <EReaderLogo onClick={onLogoClick} />
+
+      <div className="search-bar">
+        <Search size={14} />
+        <input
+          ref={searchRef}
+          type="text"
+          placeholder="Search"
+          value={searchQuery}
+          onChange={onSearchChange}
+        />
+        <span className="search-kbd">/</span>
+      </div>
+
+      <div className="sidebar-category">
+        <span className="sidebar-heading">Browse</span>
+        <div
+          className={`sidebar-item ${view === 'library' ? 'active' : ''}`}
+          onClick={() => setView('library')}
+          style={{ cursor: 'pointer' }}
+        >
+          <FileText size={16} className="icon" /> Library
+        </div>
+        <div
+          className={`sidebar-item ${view === 'reader' ? 'active' : ''}`}
+          onClick={() => { if (activeBook) setView('reader'); }}
+          style={{ cursor: activeBook ? 'pointer' : 'default', opacity: activeBook ? 1 : 0.5 }}
+        >
+          <BookOpen size={16} className="icon" /> Reading Now
+        </div>
+      </div>
+
+      <div style={{ flex: 1 }}></div>
+
+      <div className="sidebar-settings">
+        <div
+          className="sidebar-settings-header"
+          onClick={() => setShowSettings(!showSettings)}
+        >
+          <span className="sidebar-heading">Options</span>
+          <Settings size={14} style={{ color: 'var(--text-muted)' }} />
+        </div>
+
+        {showSettings && (
+          <div className="sidebar-settings-content">
+            <div className="sidebar-setting-row">
+              <label>Voice Engine</label>
+              <select value={piperVoice} onChange={onVoiceChange}>
+                <option disabled style={{ fontWeight: 600 }}>🇺🇸 US English</option>
+                <option value="en_US-lessac-medium">  Lessac — Female</option>
+                <option value="en_US-joe-medium">  Joe — Male</option>
+                <option value="en_US-libritts_r-medium">  LibriTTS — Multi</option>
+                <option disabled style={{ fontWeight: 600 }}>🇬🇧 British English</option>
+                <option value="en_GB-alan-medium">  Alan — Male</option>
+                <option value="en_GB-northern_english_male-medium">  Northern Male</option>
+                <option value="en_GB-semaine-medium">  Semaine</option>
+                <option value="en_GB-southern_english_female-low">  Southern Female</option>
+              </select>
+            </div>
+
+            <div className="sidebar-setting-row">
+              <label>Speed ({speechRate}x)</label>
+              <input type="range" min="0.5" max="2.0" step="0.1" value={speechRate} onChange={onRateChange} />
+            </div>
+          </div>
+        )}
+      </div>
+    </aside>
+  );
+}

App/frontend/src/components/TOCPopover.jsx

@@ -0,0 +1,35 @@
+import React from 'react';
+
+export default function TOCPopover({ toc, currentChunkIndex, onJump, onClose }) {
+  return (
+    <div className="toc-popover">
+      <div className="settings-section-title" style={{ padding: '0 8px', marginBottom: '12px' }}>Table of Contents</div>
+      <div className="toc-list">
+        {toc?.length > 0 ? (
+          toc.map((item, i) => {
+            const isCurrentOrPast = item.chunkIndex <= currentChunkIndex;
+            const isNextFuture = (i < toc.length - 1) ? (toc[i + 1].chunkIndex > currentChunkIndex) : true;
+            const isActive = isCurrentOrPast && isNextFuture;
+
+            return (
+              <div
+                key={i}
+                className={`toc-item ${isActive ? 'active' : ''}`}
+                onClick={() => {
+                  onJump(item.chunkIndex);
+                  onClose();
+                }}
+              >
+                {item.label}
+              </div>
+            );
+          })
+        ) : (
+          <div style={{ padding: '8px', fontSize: '14px', color: 'var(--text-secondary)' }}>
+            No contents found in this document.
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}

App/frontend/src/index.css

@@ -0,0 +1,1845 @@
+@import url('https://fonts.googleapis.com/css2?family=Instrument+Sans:ital,wght@0,400;0,500;0,600;0,700;1,400&family=Playfair+Display:ital,wght@0,400;0,700;0,800;1,400;1,700&display=swap');
+
+/* ─── Theme Transition ─── */
+*,
+*::before,
+*::after {
+  transition-property: background-color, border-color, color, box-shadow;
+  transition-duration: 0.25s;
+  transition-timing-function: cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+:root {
+  /* ── Dark Mode (Default) ── */
+  --bg-primary: #000000;
+  --bg-secondary: #0a0a0a;
+  --bg-elevated: #111111;
+  --bg-input: rgba(255, 255, 255, 0.05);
+  --bg-sidebar: rgba(0, 0, 0, 0.5);
+  --bg-header: rgba(0, 0, 0, 0.75);
+  --bg-reader-header: rgba(0, 0, 0, 0.85);
+  --bg-dock: rgba(10, 10, 10, 0.8);
+  --bg-popover: rgba(15, 15, 15, 0.92);
+  --bg-cover-content: linear-gradient(135deg, rgba(20, 20, 20, 0.9) 0%, rgba(5, 5, 5, 0.95) 100%);
+  --bg-app-gradient: radial-gradient(ellipse 80% 50% at 50% 110%, rgba(252, 255, 130, 0.04) 0%, transparent 70%), #000000;
+
+  --text-primary: #ffffff;
+  --text-secondary: #a1a1aa;
+  --text-muted: #71717a;
+  --text-body: #d4d4d8;
+  --text-body-hover: #ffffff;
+  --text-cover-author: rgba(255, 255, 255, 0.6);
+
+  /* Accent */
+  --accent: #fcff82;
+  --accent-blue: #3b82f6;
+  --accent-dim: rgba(252, 255, 130, 0.15);
+
+  /* Typography */
+  --font-display: 'Playfair Display', Georgia, serif;
+  --font-sans: 'Instrument Sans', system-ui, sans-serif;
+
+  /* Borders */
+  --border-color: rgba(255, 255, 255, 0.08);
+  --border-hover: rgba(255, 255, 255, 0.16);
+  --border-active: rgba(252, 255, 130, 0.25);
+
+  /* Shadows - Layered for depth */
+  --shadow-sm: 0 2px 4px rgba(0, 0, 0, 0.5);
+  --shadow-md: 0 8px 16px -4px rgba(0, 0, 0, 0.6), 0 0 0 1px rgba(255, 255, 255, 0.05);
+  --shadow-lg: 0 20px 48px -12px rgba(0, 0, 0, 0.8), 0 0 0 1px rgba(255, 255, 255, 0.08);
+  --shadow-dock: 0 24px 64px rgba(0, 0, 0, 0.9), 0 0 0 1px rgba(255, 255, 255, 0.1);
+
+  /* UI Tokens */
+  --radius-xs: 6px;
+  --radius-sm: 10px;
+  --radius-md: 16px;
+  --radius-lg: 28px;
+  --radius-full: 9999px;
+
+  /* Spacing Scale (8dp system) */
+  --space-1: 0.25rem;
+  /* 4px */
+  --space-2: 0.5rem;
+  /* 8px */
+  --space-3: 0.75rem;
+  /* 12px */
+  --space-4: 1rem;
+  /* 16px */
+  --space-5: 1.5rem;
+  /* 24px */
+  --space-6: 2rem;
+  /* 32px */
+  --space-8: 3rem;
+  /* 48px */
+  --space-10: 4rem;
+  /* 64px */
+
+  /* Input/select styles */
+  --select-bg: rgba(255, 255, 255, 0.06);
+  --select-bg-hover: rgba(255, 255, 255, 0.08);
+  --select-arrow: rgba(255, 255, 255, 0.5);
+  --select-option-bg: #1a1a1a;
+  --select-option-color: #ffffff;
+  --select-disabled-color: #52525b;
+  --range-track: rgba(255, 255, 255, 0.12);
+  --scrubber-track: rgba(255, 255, 255, 0.08);
+  --scrubber-fill: rgba(255, 255, 255, 0.35);
+  --progress-bar-track: rgba(255, 255, 255, 0.08);
+  --progress-bar-fill: rgba(255, 255, 255, 0.35);
+  --scrollbar-thumb: rgba(255, 255, 255, 0.1);
+  --spinner-border: rgba(255, 255, 255, 0.15);
+  --sidebar-item-hover: rgba(255, 255, 255, 0.04);
+  --sidebar-item-active: rgba(255, 255, 255, 0.08);
+  --sidebar-item-active-border: rgba(255, 255, 255, 0.12);
+  --btn-icon-hover: rgba(255, 255, 255, 0.08);
+  --btn-icon-active: rgba(255, 255, 255, 0.1);
+  --btn-icon-active-shadow: rgba(255, 255, 255, 0.15);
+  --btn-text-border: rgba(255, 255, 255, 0.18);
+  --toc-hover: rgba(255, 255, 255, 0.05);
+  --toc-active: rgba(255, 255, 255, 0.04);
+  --toc-active-border: rgba(255, 255, 255, 0.1);
+  --dock-btn-hover: rgba(255, 255, 255, 0.08);
+  --dock-play-border: rgba(255, 255, 255, 0.2);
+  --reader-content-scrollbar: rgba(255, 255, 255, 0.08);
+  --color-scheme: dark;
+
+  /* Reader typography (overridden via JS) */
+  --reader-font: 'Playfair Display', Georgia, serif;
+  --reader-line-height: 2.0;
+  --reader-letter-spacing: 0em;
+  --reader-para-spacing: 1.85rem;
+
+  /* Transitions */
+  --transition-fast: all 0.15s cubic-bezier(0.4, 0, 0.2, 1);
+  --transition-base: all 0.25s cubic-bezier(0.4, 0, 0.2, 1);
+  --transition-slow: all 0.4s cubic-bezier(0.4, 0, 0.2, 1);
+  --transition-spring: all 0.5s cubic-bezier(0.175, 0.885, 0.32, 1.275);
+}
+
+/* ─── Light Theme ─────────────────────────────────────── */
+[data-theme="light"] {
+  --bg-primary: #fbfbf8;
+  /* Warm paper editorial tone */
+  --bg-secondary: #f4f4f2;
+  --bg-elevated: #ffffff;
+  --bg-input: rgba(0, 0, 0, 0.04);
+  --bg-sidebar: rgba(255, 255, 255, 0.65);
+  --bg-header: rgba(255, 255, 255, 0.75);
+  --bg-reader-header: rgba(255, 255, 255, 0.85);
+  --bg-dock: rgba(255, 255, 255, 0.8);
+  --bg-popover: rgba(255, 255, 255, 0.96);
+  --bg-cover-content: linear-gradient(135deg, rgba(230, 225, 215, 0.9) 0%, rgba(215, 210, 200, 0.95) 100%);
+  --bg-app-gradient: radial-gradient(ellipse 80% 50% at 50% 110%, rgba(0, 71, 255, 0.02) 0%, transparent 70%), #fbfbf8;
+
+  --text-primary: #18181b;
+  /* Deep coal */
+  --text-secondary: #52525b;
+  --text-muted: #94949e;
+  --text-body: #27272a;
+  --text-body-hover: #000000;
+  --text-cover-author: rgba(0, 0, 0, 0.55);
+
+  /* Accent stays distinctive */
+  --accent: #fcff82;
+  --accent-blue: #2563eb;
+  --accent-dim: rgba(252, 255, 130, 0.3);
+
+  --border-color: rgba(0, 0, 0, 0.08);
+  --border-hover: rgba(0, 0, 0, 0.16);
+  --border-active: rgba(0, 0, 0, 0.25);
+
+  --shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.1);
+  --shadow-md: 0 4px 16px rgba(0, 0, 0, 0.1), 0 0 0 1px rgba(0, 0, 0, 0.06);
+  --shadow-lg: 0 12px 40px rgba(0, 0, 0, 0.14), 0 0 0 1px rgba(0, 0, 0, 0.07);
+  --shadow-dock: 0 24px 48px rgba(0, 0, 0, 0.15), 0 0 0 1px rgba(0, 0, 0, 0.1);
+
+  /* Input/select overrides */
+  --select-bg: rgba(0, 0, 0, 0.05);
+  --select-bg-hover: rgba(0, 0, 0, 0.08);
+  --select-arrow: rgba(0, 0, 0, 0.45);
+  --select-option-bg: #f7f5f0;
+  --select-option-color: #1a1a1a;
+  --select-disabled-color: #a8a29e;
+  --range-track: rgba(0, 0, 0, 0.12);
+  --scrubber-track: rgba(0, 0, 0, 0.12);
+  --scrubber-fill: rgba(0, 0, 0, 0.3);
+  --progress-bar-track: rgba(0, 0, 0, 0.08);
+  --progress-bar-fill: rgba(0, 0, 0, 0.3);
+  --scrollbar-thumb: rgba(0, 0, 0, 0.12);
+  --spinner-border: rgba(0, 0, 0, 0.12);
+  --sidebar-item-hover: rgba(0, 0, 0, 0.04);
+  --sidebar-item-active: rgba(0, 0, 0, 0.08);
+  --sidebar-item-active-border: rgba(0, 0, 0, 0.12);
+  --btn-icon-hover: rgba(0, 0, 0, 0.06);
+  --btn-icon-active: rgba(0, 0, 0, 0.08);
+  --btn-icon-active-shadow: rgba(0, 0, 0, 0.12);
+  --btn-text-border: rgba(0, 0, 0, 0.2);
+  --toc-hover: rgba(0, 0, 0, 0.05);
+  --toc-active: rgba(0, 0, 0, 0.05);
+  --toc-active-border: rgba(0, 0, 0, 0.1);
+  --dock-btn-hover: rgba(0, 0, 0, 0.06);
+  --dock-play-border: rgba(0, 0, 0, 0.2);
+  --reader-content-scrollbar: rgba(0, 0, 0, 0.1);
+  --color-scheme: light;
+}
+
+/* ─── Reset ─────────────────────────────────────────── */
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+
+body {
+  font-family: var(--font-sans);
+  background-color: var(--bg-primary);
+  color: var(--text-primary);
+  line-height: 1.65;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  overflow: hidden;
+}
+
+#root {
+  height: 100vh;
+  display: flex;
+}
+
+/* ─── App Container ──────────────────────────────────── */
+.app-container {
+  display: flex;
+  height: 100vh;
+  width: 100vw;
+  overflow: hidden;
+  background: var(--bg-app-gradient);
+}
+
+/* ─── Sidebar ────────────────────────────────────────── */
+.sidebar {
+  width: 260px;
+  flex-shrink: 0;
+  border-right: 1px solid var(--border-color);
+  background: var(--bg-sidebar);
+  backdrop-filter: blur(20px);
+  -webkit-backdrop-filter: blur(20px);
+  display: flex;
+  flex-direction: column;
+  padding: 1.75rem 1.25rem;
+  z-index: 10;
+}
+
+/* Logo area */
+.sidebar-logo {
+  padding: 0 0.5rem;
+  margin-bottom: 2rem;
+}
+
+.search-bar {
+  background: var(--bg-input);
+  border: 1px solid var(--border-color);
+  border-radius: var(--radius-full);
+  padding: 0.65rem 1.1rem;
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  color: var(--text-muted);
+  font-size: 0.875rem;
+  margin-bottom: 2rem;
+  transition: var(--transition);
+}
+
+.search-bar:focus-within {
+  border-color: var(--border-hover);
+  box-shadow: 0 0 0 3px rgba(255, 255, 255, 0.04);
+  color: var(--text-secondary);
+}
+
+.search-bar input {
+  border: none;
+  background: transparent;
+  outline: none;
+  color: var(--text-primary);
+  width: 100%;
+  font-family: var(--font-sans);
+  font-size: 0.875rem;
+}
+
+.search-bar input::placeholder {
+  color: var(--text-muted);
+}
+
+.sidebar-settings {
+  border-top: none;
+  padding-bottom: 20px;
+}
+
+.sidebar-settings-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 0 8px;
+  margin-bottom: 16px;
+  cursor: pointer;
+}
+
+.sidebar-settings-content {
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+  padding: 0 4px;
+}
+
+.sidebar-setting-row label {
+  font-size: 11px;
+  color: var(--text-muted);
+  display: block;
+  margin-bottom: 6px;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+.sidebar-setting-row select,
+.sidebar-setting-row input[type="range"] {
+  width: 100%;
+}
+
+.search-kbd {
+  font-size: 10px;
+  color: var(--text-muted);
+  border: 1px solid rgba(255, 255, 255, 0.1);
+  padding: 2px 5px;
+  border-radius: 4px;
+  letter-spacing: 0;
+  pointer-events: none;
+}
+
+.sidebar-section {
+  margin-bottom: 2rem;
+}
+
+.sidebar-heading {
+  font-family: var(--font-sans);
+  font-size: 0.7rem;
+  /* 11.2px - Microcopy standard */
+  font-weight: 700;
+  color: var(--text-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.18em;
+  margin-bottom: 1rem;
+  padding-left: 0.75rem;
+  display: block;
+}
+
+.sidebar-category {
+  margin-bottom: 2.25rem;
+}
+
+.sidebar-item {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 0.75rem 1rem;
+  margin-bottom: 4px;
+  font-size: 0.93rem;
+  font-weight: 500;
+  color: var(--text-secondary);
+  cursor: pointer;
+  transition: var(--transition-fast);
+  border-radius: var(--radius-md);
+  border: 1px solid transparent;
+  user-select: none;
+}
+
+.sidebar-item:hover {
+  background: var(--sidebar-item-hover);
+  color: var(--text-primary);
+  transform: translateX(2px);
+}
+
+.sidebar-item:active {
+  transform: scale(0.98);
+}
+
+.sidebar-item.active {
+  background: var(--sidebar-item-active);
+  color: var(--text-primary);
+  border-color: var(--sidebar-item-active-border);
+  font-weight: 600;
+}
+
+.sidebar-item .icon {
+  color: var(--text-muted);
+  display: flex;
+  flex-shrink: 0;
+  transition: color 0.15s ease;
+}
+
+.sidebar-item:hover .icon,
+.sidebar-item.active .icon {
+  color: var(--text-primary);
+}
+
+/* ─── Main Content ───────────────────────────────────── */
+.main-content {
+  flex: 1;
+  background: transparent;
+  display: flex;
+  flex-direction: column;
+  position: relative;
+  overflow-y: auto;
+}
+
+.main-content::-webkit-scrollbar {
+  width: 4px;
+}
+
+.main-content::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+.main-content::-webkit-scrollbar-thumb {
+  background: var(--scrollbar-thumb);
+  border-radius: var(--radius-full);
+}
+
+/* ─── Header ─────────────────────────────────────────── */
+.header {
+  height: 80px;
+  padding: 0 3.5rem;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  border-bottom: 1px solid var(--border-color);
+  position: sticky;
+  top: 0;
+  z-index: 10;
+  background: var(--bg-header);
+  backdrop-filter: blur(16px);
+  -webkit-backdrop-filter: blur(16px);
+}
+
+.header-title {
+  font-family: var(--font-display);
+  font-size: 2.2rem;
+  font-weight: 700;
+  font-style: italic;
+  letter-spacing: -0.01em;
+  color: var(--text-primary);
+}
+
+.btn-pill {
+  background: var(--bg-elevated);
+  border: 1px solid var(--border-color);
+  color: var(--text-secondary);
+  padding: 0.5rem 1.25rem;
+  border-radius: var(--radius-full);
+  font-family: var(--font-sans);
+  font-size: 0.72rem;
+  font-weight: 600;
+  cursor: pointer;
+  transition: var(--transition-fast);
+}
+
+.btn-pill:hover {
+  background: var(--btn-icon-hover);
+  color: var(--text-primary);
+  border-color: var(--border-hover);
+}
+
+.dropdown-menu {
+  background: var(--bg-popover);
+  border: 1px solid var(--border-color);
+  border-radius: var(--radius-md);
+  box-shadow: var(--shadow-lg);
+  overflow: hidden;
+  box-sizing: border-box;
+  backdrop-filter: blur(20px);
+  -webkit-backdrop-filter: blur(20px);
+  animation: dropdownEnter 0.2s cubic-bezier(0.16, 1, 0.3, 1) both;
+}
+
+.dropdown-item {
+  display: block;
+  width: 100%;
+  padding: 0.75rem 1rem;
+  border: none;
+  background: transparent;
+  color: var(--text-secondary);
+  font-family: var(--font-sans);
+  font-size: 0.82rem;
+  font-weight: 500;
+  text-align: left;
+  cursor: pointer;
+  transition: var(--transition-fast);
+}
+
+.dropdown-item:hover {
+  background: var(--btn-icon-hover);
+  color: var(--text-primary);
+}
+
+.dropdown-item.active {
+  background: var(--text-primary);
+  color: var(--bg-primary);
+  font-weight: 600;
+}
+
+@keyframes dropdownEnter {
+  from {
+    opacity: 0;
+    transform: translateY(-4px) scale(0.98);
+  }
+
+  to {
+    opacity: 1;
+    transform: translateY(0) scale(1);
+  }
+}
+
+.header-actions {
+  display: flex;
+  gap: 1rem;
+  align-items: center;
+}
+
+/* ─── Buttons ────────────────────────────────────────── */
+.btn-icon {
+  background: transparent;
+  border: none;
+  color: var(--text-secondary);
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  transition: var(--transition-fast);
+  padding: 0;
+  border-radius: var(--radius-full);
+  width: 44px;
+  /* Rule 86: 44px touch target */
+  height: 44px;
+  flex-shrink: 0;
+  outline: none;
+}
+
+.btn-icon:hover {
+  color: var(--text-primary);
+  background: var(--btn-icon-hover);
+}
+
+.btn-icon:active {
+  transform: scale(0.96);
+  /* Rule 197: scale feedback */
+  background: var(--btn-icon-active);
+}
+
+.btn-icon.active {
+  color: var(--text-primary);
+  background: var(--btn-icon-active);
+  box-shadow: 0 0 0 1px var(--btn-icon-active-shadow);
+}
+
+/* Page Animations */
+.page-enter {
+  animation: pageEnter 0.55s cubic-bezier(0.16, 1, 0.3, 1) both;
+}
+
+@keyframes pageEnter {
+  from {
+    opacity: 0;
+    transform: scale(0.985) translateY(10px);
+  }
+
+  to {
+    opacity: 1;
+    transform: scale(1) translateY(0);
+  }
+}
+
+@keyframes slideUp {
+  from {
+    opacity: 0;
+    transform: translateY(20px);
+  }
+
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.btn-text {
+  background: transparent;
+  border: 1px solid var(--btn-text-border);
+  color: var(--text-primary);
+  padding: 0.55rem 1.4rem;
+  font-size: 0.75rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.1em;
+  border-radius: var(--radius-full);
+  cursor: pointer;
+  transition: var(--transition);
+  font-family: var(--font-sans);
+}
+
+.btn-text:hover,
+.btn-text.active {
+  background: var(--text-primary);
+  color: var(--bg-primary);
+  border-color: var(--text-primary);
+}
+
+.btn-text:hover {
+  transform: translateY(-1px);
+}
+
+.btn-text:active {
+  transform: translateY(0) scale(0.98);
+}
+
+/* ─── Theme Toggle Button ────────────────────────────── */
+.theme-toggle {
+  background: transparent;
+  border: 1px solid var(--border-color);
+  color: var(--text-secondary);
+  cursor: pointer;
+  width: 40px;
+  height: 40px;
+  border-radius: var(--radius-full);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  transition: var(--transition-fast);
+  flex-shrink: 0;
+  font-size: 1rem;
+  line-height: 1;
+}
+
+.theme-toggle:hover {
+  background: var(--btn-icon-hover);
+  color: var(--text-primary);
+  border-color: var(--border-hover);
+}
+
+.library-grid {
+  padding: 3.5rem 3.5rem 6rem;
+  /* Top padding added to prevent header overlap */
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(210px, 1fr));
+  gap: 3.5rem 2.5rem;
+  animation: fadeInUp 0.5s cubic-bezier(0.16, 1, 0.3, 1) both;
+}
+
+.book-card {
+  display: flex;
+  flex-direction: column;
+  cursor: pointer;
+  position: relative;
+  transition: var(--transition);
+  animation: fadeInUp 0.4s cubic-bezier(0.16, 1, 0.3, 1) both;
+  max-width: 320px;
+}
+
+/* ─── Book Cover ─────────────────────────────────────── */
+.book-cover {
+  width: 100%;
+  height: 315px;
+  background: var(--bg-elevated);
+  border: 1px solid var(--border-color);
+  border-radius: var(--radius-sm);
+  margin-bottom: 1.15rem;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  overflow: hidden;
+  position: relative;
+  box-shadow: var(--shadow-sm);
+  transition: var(--transition);
+}
+
+.book-card:hover .book-cover {
+  border-color: var(--border-hover);
+  box-shadow: var(--shadow-lg);
+}
+
+/* Hover translation removed for stability */
+
+/* Empty State */
+.empty-library {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  padding: 4rem 2rem;
+  text-align: center;
+  min-height: calc(100vh - 200px);
+}
+
+.btn-primary {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.75rem;
+  background-color: var(--accent);
+  color: #000;
+  padding: 0.8rem 1.75rem;
+  border: 2px solid #000;
+  border-radius: var(--radius-sm);
+  font-family: var(--font-sans);
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  font-size: 0.8rem;
+  box-shadow: 4px 4px 0px 0px #000;
+  transition: transform 0.1s ease, box-shadow 0.1s ease;
+  cursor: pointer;
+}
+
+.btn-primary:hover {
+  transform: translate(-1px, -1px);
+  box-shadow: 5px 5px 0px 0px #000;
+}
+
+.book-cover-content {
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  align-items: center;
+  height: 100%;
+  width: 100%;
+  padding: 1.5rem;
+  text-align: center;
+  background: var(--bg-cover-content);
+}
+
+.default-cover-title {
+  color: var(--text-primary);
+  font-family: var(--font-display);
+  font-weight: 700;
+  font-style: italic;
+  font-size: 1.3rem;
+  line-height: 1.2;
+  display: -webkit-box;
+  -webkit-line-clamp: 4;
+  line-clamp: 4;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+  margin-bottom: 1rem;
+}
+
+.default-cover-author {
+  color: var(--text-cover-author);
+  font-family: var(--font-sans);
+  font-weight: 500;
+  font-size: 0.68rem;
+  text-transform: uppercase;
+  letter-spacing: 0.14em;
+  position: relative;
+  z-index: 1;
+}
+
+.book-cover img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  transition: var(--transition);
+  filter: brightness(0.88);
+}
+
+.book-card:hover .book-cover img {
+  filter: brightness(1.0);
+}
+
+/* Delete button on cover */
+.delete-book-btn {
+  position: absolute;
+  top: 0.65rem;
+  right: 0.65rem;
+  width: 32px;
+  /* Scaled down for cleanliness */
+  height: 32px;
+  background: rgba(0, 0, 0, 0.7);
+  backdrop-filter: blur(12px);
+  -webkit-backdrop-filter: blur(12px);
+  color: #ffffff;
+  border: 1px solid rgba(255, 255, 255, 0.2);
+  border-radius: var(--radius-full);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 20;
+  opacity: 0;
+  transform: scale(0.9) translateY(-2px);
+  transition: all 0.2s cubic-bezier(0.16, 1, 0.3, 1);
+  cursor: pointer;
+}
+
+.book-card:hover .delete-book-btn {
+  opacity: 1;
+  transform: scale(1) translateY(0);
+}
+
+.delete-book-btn:hover {
+  background: #ffffff;
+  border-color: #ffffff;
+  color: #000000;
+  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.3);
+}
+
+.delete-book-btn:active {
+  transform: scale(0.92);
+}
+
+.book-card.is-parsing {
+  cursor: default;
+  opacity: 0.8;
+  filter: grayscale(0.2);
+}
+
+.book-card.is-parsing:hover {
+  transform: scale(1.0);
+}
+
+.parsing-overlay {
+  position: absolute;
+  inset: 0;
+  background: rgba(0, 0, 0, 0.4);
+  backdrop-filter: blur(2px);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 5;
+}
+
+.spinner-small {
+  width: 24px;
+  height: 24px;
+  border: 2px solid rgba(255, 255, 255, 0.2);
+  border-top-color: #fff;
+  border-radius: 50%;
+  animation: spin 0.8s linear infinite;
+}
+
+.book-title {
+  font-family: var(--font-display);
+  font-size: 1.05rem;
+  font-weight: 400;
+  color: var(--text-primary);
+  line-height: 1.35;
+  margin-bottom: 0.3rem;
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+}
+
+.book-author {
+  font-family: var(--font-sans);
+  font-size: 0.78rem;
+  color: var(--text-secondary);
+  margin-bottom: 0.6rem;
+}
+
+.book-progress {
+  font-family: var(--font-sans);
+  font-size: 0.72rem;
+  color: var(--text-muted);
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+}
+
+/* Progress bar under book cards */
+.book-progress-bar-track {
+  flex: 1;
+  height: 2px;
+  background: var(--progress-bar-track);
+  border-radius: var(--radius-full);
+  overflow: hidden;
+}
+
+.book-progress-bar-fill {
+  height: 100%;
+  background: var(--progress-bar-fill);
+  border-radius: var(--radius-full);
+  transition: width 0.4s ease;
+}
+
+/* Book counts and labels */
+.book-count {
+  font-size: 0.72rem;
+  font-weight: 700;
+  letter-spacing: 0.12rem;
+  opacity: 0.5;
+  text-transform: uppercase;
+  color: var(--text-primary);
+}
+
+/* Book progress tracking */
+.book-progress-container {
+  margin-top: auto;
+  padding-top: 1rem;
+}
+
+.book-progress-labels {
+  display: flex;
+  justify-content: space-between;
+  font-size: 0.65rem;
+  font-weight: 700;
+  color: var(--text-muted);
+  margin-bottom: 0.5rem;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+}
+
+.book-progress-track {
+  height: 2px;
+  background: var(--border-color);
+  width: 100%;
+  border-radius: var(--radius-full);
+  overflow: hidden;
+}
+
+.book-progress-fill {
+  height: 100%;
+  background: var(--text-secondary);
+  transition: width 0.35s ease;
+}
+
+/* ─── Empty State ────────────────────────────────────── */
+@keyframes pulseGlow {
+
+  0%,
+  100% {
+    box-shadow: 0 0 0 0 rgba(252, 255, 130, 0);
+  }
+
+  50% {
+    box-shadow: 0 0 30px 4px rgba(252, 255, 130, 0.08);
+  }
+}
+
+.empty-state {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  flex: 1;
+  color: var(--text-muted);
+  text-align: center;
+  padding: 3rem;
+  animation: fadeInUp 0.6s cubic-bezier(0.16, 1, 0.3, 1) both;
+}
+
+.empty-state-icon {
+  width: 80px;
+  height: 80px;
+  border-radius: 50%;
+  background: var(--bg-input);
+  border: 1px solid var(--border-color);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  margin-bottom: 2rem;
+  animation: pulseGlow 3s ease-in-out infinite;
+}
+
+.empty-state h2 {
+  font-family: var(--font-display);
+  font-size: 2.25rem;
+  font-weight: 400;
+  font-style: italic;
+  color: var(--text-primary);
+  margin-bottom: 1rem;
+  letter-spacing: -0.01em;
+}
+
+.empty-state p {
+  font-family: var(--font-sans);
+  font-size: 0.95rem;
+  margin-bottom: 2.5rem;
+  max-width: 340px;
+  line-height: 1.7;
+  color: var(--text-secondary);
+}
+
+/* ─── Reader View ────────────────────────────────────── */
+@keyframes slideUpFade {
+  from {
+    opacity: 0;
+    transform: translateY(12px);
+  }
+
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.reader-wrapper {
+  background-color: var(--bg-primary);
+  color: var(--text-primary);
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+  position: absolute;
+  inset: 0;
+  z-index: 20;
+  animation: slideUpFade 0.45s cubic-bezier(0.16, 1, 0.3, 1) forwards;
+}
+
+.reader-header {
+  height: 72px;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 0 3.5rem;
+  border-bottom: 1px solid var(--border-color);
+  background: var(--bg-reader-header);
+  backdrop-filter: blur(16px);
+  -webkit-backdrop-filter: blur(16px);
+  position: relative;
+  z-index: 10;
+  flex-shrink: 0;
+}
+
+.reader-progress-bar {
+  position: absolute;
+  bottom: 0;
+  left: 0;
+  height: 1px;
+  background: var(--accent);
+  transition: width 0.3s ease;
+  opacity: 0.7;
+}
+
+.reader-content {
+  flex: 1;
+  overflow-y: auto;
+  padding: 5rem 2rem 18rem;
+  display: flex;
+  justify-content: center;
+  scroll-behavior: smooth;
+}
+
+.reader-content::-webkit-scrollbar {
+  width: 4px;
+}
+
+.reader-content::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+.reader-content::-webkit-scrollbar-thumb {
+  background: var(--reader-content-scrollbar);
+  border-radius: var(--radius-full);
+}
+
+/* ─── Book Text ──────────────────────────────────────── */
+.book-page {
+  max-width: 680px;
+  width: 100%;
+  font-size: 1.2rem;
+  line-height: var(--reader-line-height);
+  color: var(--text-primary);
+  font-family: var(--reader-font);
+  letter-spacing: var(--reader-letter-spacing);
+  transition: font-family 0.3s ease, line-height 0.3s ease, letter-spacing 0.3s ease;
+}
+
+.book-page h1,
+.book-page h2,
+.book-page h3,
+.book-page h4,
+.book-page h5,
+.book-page h6 {
+  font-family: var(--font-display);
+  font-weight: 400;
+  color: var(--text-primary);
+  margin-top: 4.5rem;
+  margin-bottom: 1.75rem;
+  line-height: 1.2;
+}
+
+.book-page h1 {
+  font-size: 3rem;
+  font-style: italic;
+}
+
+.book-page h2 {
+  font-size: 2.25rem;
+}
+
+.book-page h3 {
+  font-size: 1.75rem;
+}
+
+.book-page h4,
+.book-page h5,
+.book-page h6 {
+  font-size: 1.4rem;
+}
+
+.book-page p {
+  margin-bottom: var(--reader-para-spacing);
+  text-align: left;
+  font-family: var(--reader-font);
+  color: var(--text-body);
+  font-weight: 400;
+  cursor: text;
+  letter-spacing: var(--reader-letter-spacing);
+  line-height: var(--reader-line-height);
+  transition: color 0.2s ease, margin-bottom 0.3s ease, letter-spacing 0.3s ease, line-height 0.3s ease;
+}
+
+.book-page p:hover {
+  color: var(--text-body-hover);
+}
+
+/* ─── Audio Dock ─────────────────────────────────────── */
+.audio-dock {
+  position: absolute;
+  bottom: 2.5rem;
+  left: 50%;
+  transform: translateX(-50%);
+  background: var(--bg-dock);
+  backdrop-filter: blur(28px) saturate(180%);
+  -webkit-backdrop-filter: blur(28px) saturate(180%);
+  border: 1px solid var(--border-color);
+  border-radius: var(--radius-full);
+  padding: 1.1rem 2.25rem;
+  display: flex;
+  align-items: center;
+  gap: 2.25rem;
+  z-index: 50;
+  width: min(88%, 740px);
+  box-shadow: var(--shadow-dock);
+  transition: var(--transition);
+}
+
+.audio-dock:hover {
+  border-color: var(--border-hover);
+}
+
+.dock-info {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  min-width: 0;
+}
+
+.dock-title {
+  font-family: var(--font-display);
+  font-size: 1.05rem;
+  font-weight: 400;
+  font-style: italic;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  color: var(--text-primary);
+}
+
+.dock-subtitle {
+  font-family: var(--font-sans);
+  font-size: 0.7rem;
+  /* 11px Microcopy */
+  text-transform: uppercase;
+  letter-spacing: 0.16em;
+  color: var(--text-muted);
+  margin-top: 0.35rem;
+}
+
+.dock-controls {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+}
+
+.dock-btn {
+  background: transparent;
+  border: none;
+  color: var(--text-secondary);
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  transition: var(--transition-fast);
+  border-radius: var(--radius-full);
+  width: 44px;
+  /* Rule 86: 44px touch target */
+  height: 44px;
+  flex-shrink: 0;
+}
+
+.dock-btn:hover {
+  background: var(--dock-btn-hover);
+  color: var(--text-primary);
+}
+
+.dock-btn.play {
+  width: 52px;
+  height: 52px;
+  border: 1px solid var(--dock-play-border);
+  color: var(--text-primary);
+}
+
+.dock-btn.play:hover {
+  background: var(--text-primary);
+  border-color: var(--text-primary);
+  color: var(--bg-primary);
+  transform: scale(1.04);
+}
+
+.dock-btn.play:active {
+  transform: scale(0.97);
+}
+
+.dock-progress {
+  display: flex;
+  align-items: center;
+  gap: 1rem;
+  font-family: var(--font-sans);
+  font-size: 0.68rem;
+  color: var(--text-muted);
+  font-variant-numeric: tabular-nums;
+  margin-top: 0.85rem;
+  letter-spacing: 0.03em;
+}
+
+.scrubber {
+  flex: 1;
+  height: 2px;
+  background: var(--scrubber-track);
+  position: relative;
+  cursor: pointer;
+  border-radius: var(--radius-full);
+  margin: 0 4px;
+  transition: height 0.2s cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+.scrubber:hover {
+  height: 4px;
+}
+
+.scrubber-fill {
+  position: absolute;
+  top: 0;
+  left: 0;
+  height: 100%;
+  background: var(--scrubber-fill);
+  border-radius: var(--radius-full);
+  transition: width 0.25s linear, background-color 0.2s ease;
+}
+
+.scrubber:hover .scrubber-fill {
+  background: var(--text-primary);
+}
+
+.scrubber-thumb {
+  position: absolute;
+  top: 50%;
+  width: 12px;
+  height: 12px;
+  background: var(--text-primary);
+  border-radius: 50%;
+  transform: translate(-50%, -50%) scale(0);
+  transition: transform 0.2s cubic-bezier(0.16, 1, 0.3, 1);
+  box-shadow: var(--shadow-sm);
+  pointer-events: none;
+  z-index: 2;
+}
+
+.scrubber:hover .scrubber-thumb {
+  transform: translate(-50%, -50%) scale(1);
+}
+
+/* ─── Spinner ─────────────────────────────��──────────── */
+.spinner {
+  width: 20px;
+  height: 20px;
+  border: 2px solid var(--spinner-border);
+  border-top-color: var(--text-primary);
+  border-radius: 50%;
+  animation: spin 0.75s linear infinite;
+}
+
+@keyframes spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+/* ─── Popovers ───────────────────────────────────────── */
+.book-page p,
+.book-page h1,
+.book-page h2,
+.book-page h3,
+.book-page h4,
+.book-page h5,
+.book-page h6 {
+  transition: opacity 0.4s ease, color 0.4s ease, background-color 0.4s ease;
+}
+
+/* ════════════════════════════════════════════════════════
+   SETTINGS PANEL — Matches app button + UI language
+   ════════════════════════════════════════════════════════ */
+
+.settings-popover {
+  position: absolute;
+  top: 68px;
+  right: 1.5rem;
+  z-index: 200;
+  width: 320px;
+  background: var(--bg-popover);
+  border: 1px solid var(--border-color);
+  border-radius: var(--radius-md);
+  box-shadow: var(--shadow-lg);
+  overflow: hidden;
+  display: flex;
+  flex-direction: column;
+  animation: spEnter 0.2s cubic-bezier(0.16, 1, 0.3, 1) both;
+  /* Blur same as sidebar/header */
+  backdrop-filter: blur(20px);
+  -webkit-backdrop-filter: blur(20px);
+}
+
+@keyframes spEnter {
+  from {
+    opacity: 0;
+    transform: translateY(-6px) scale(0.98);
+  }
+
+  to {
+    opacity: 1;
+    transform: translateY(0) scale(1);
+  }
+}
+
+/* ── Panel header ──────────────────────────────────────── */
+.sp-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 0.9rem 1.25rem 0.75rem;
+  border-bottom: 1px solid var(--border-color);
+}
+
+.sp-title {
+  font-family: var(--font-display);
+  font-style: italic;
+  font-weight: 400;
+  font-size: 1rem;
+  color: var(--text-primary);
+  letter-spacing: -0.01em;
+}
+
+/* Close button reuses btn-icon — just size override */
+.sp-close {
+  width: 30px !important;
+  height: 30px !important;
+  padding: 0 !important;
+  color: var(--text-muted) !important;
+  flex-shrink: 0;
+}
+
+.sp-close:hover {
+  color: var(--text-primary) !important;
+}
+
+/* ── Groups ────────────────────────────────────────────── */
+.sp-group {
+  padding: 0.875rem 1.25rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.6rem;
+  border-bottom: 1px solid var(--border-color);
+}
+
+.sp-group:last-child {
+  border-bottom: none;
+}
+
+.sp-group-label {
+  font-family: var(--font-sans);
+  font-size: 0.7rem;
+  /* 11px Microcopy */
+  font-weight: 700;
+  letter-spacing: 0.16em;
+  text-transform: uppercase;
+  color: var(--text-muted);
+  margin-bottom: 0.4rem;
+}
+
+/* ── Rows ──────────────────────────────────────────────── */
+.sp-row {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  min-height: 36px;
+  /* comfortable click target */
+}
+
+.sp-row-col {
+  flex-direction: column;
+  align-items: stretch;
+  gap: 0.4rem;
+  min-height: unset;
+}
+
+.sp-row-label {
+  font-family: var(--font-sans);
+  font-size: 0.75rem;
+  font-weight: 500;
+  color: var(--text-secondary);
+  min-width: 48px;
+  flex-shrink: 0;
+}
+
+/* Label + badge on same line (used in Spacing row) */
+.sp-label-between {
+  display: flex;
+  align-items: baseline;
+  justify-content: space-between;
+}
+
+.sp-step-badge {
+  font-family: var(--font-sans);
+  font-size: 0.7rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.12em;
+  color: var(--text-muted);
+}
+
+/* Discrete step slider (Spacing) */
+.sp-step-wrap {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+
+.sp-step-ticks {
+  display: flex;
+  justify-content: space-between;
+  padding: 0 2px;
+}
+
+.sp-tick {
+  font-family: var(--font-sans);
+  font-size: 0.7rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--text-muted);
+  cursor: pointer;
+  padding: 4px 8px;
+  transition: color 0.12s ease;
+  user-select: none;
+}
+
+.sp-tick:hover {
+  color: var(--text-secondary);
+}
+
+.sp-tick.active {
+  color: var(--text-primary);
+}
+
+/* Theme switcher — icon + label buttons filling full width */
+.sp-theme-row {
+  display: flex;
+  gap: 6px;
+}
+
+.sp-theme-btn {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 5px;
+  padding: 0.7rem 0.5rem 0.6rem;
+  background: transparent;
+  border: 1px solid var(--btn-text-border);
+  border-radius: var(--radius-sm);
+  color: var(--text-muted);
+  cursor: pointer;
+  transition: background 0.15s ease, color 0.15s ease, border-color 0.15s ease;
+  font-family: var(--font-sans);
+}
+
+.sp-theme-btn span {
+  font-size: 0.62rem;
+  font-weight: 600;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+  line-height: 1;
+}
+
+.sp-theme-btn:hover {
+  background: var(--btn-icon-hover);
+  color: var(--text-primary);
+  border-color: var(--border-hover);
+}
+
+.sp-theme-btn.active {
+  background: var(--text-primary);
+  color: var(--bg-primary);
+  border-color: var(--text-primary);
+}
+
+.sp-theme-btn.active svg {
+  stroke: var(--bg-primary);
+}
+
+/* Font select — show selected font in its typeface */
+.sp-font-select {
+  font-family: var(--reader-font);
+}
+
+/* Highlight color swatches */
+.sp-color-row {
+  display: grid;
+  grid-template-columns: repeat(6, 1fr);
+  gap: 8px;
+  padding: 4px 0;
+}
+
+.sp-color-btn {
+  aspect-ratio: 1;
+  border-radius: 50%;
+  border: 1px solid var(--border-color);
+  background: var(--swatch-bg);
+  cursor: pointer;
+  transition: transform 0.2s ease, box-shadow 0.2s ease;
+  padding: 0;
+  position: relative;
+}
+
+.sp-color-btn:hover {
+  transform: scale(1.1);
+  border-color: var(--text-muted);
+}
+
+.sp-color-btn.active {
+  transform: scale(1.1);
+  box-shadow: 0 0 0 2px var(--bg-popover), 0 0 0 4px var(--text-primary);
+  border-color: transparent;
+  z-index: 1;
+}
+
+:root {
+  --highlight-color: #fcff82;
+}
+
+
+/* ── Option buttons — match .btn-text language exactly ─── */
+/*
+  App's .btn-text uses:
+    border: 1px solid var(--btn-text-border)
+    border-radius: var(--radius-full)  ← pill
+    uppercase, 0.75rem, weight 600, letter-spacing 0.1em
+    hover → inverted (bg=text-primary, color=bg-primary)
+  We mirror that exactly for the options.
+*/
+.sp-options {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  flex: 1;
+}
+
+.sp-opt {
+  /* Same base as .btn-text */
+  background: transparent;
+  border: 1px solid var(--btn-text-border);
+  color: var(--text-secondary);
+  padding: 0.38rem 0.85rem;
+  font-size: 0.72rem;
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.1em;
+  border-radius: var(--radius-full);
+  /* pill — matches app buttons */
+  cursor: pointer;
+  transition: background 0.15s ease, color 0.15s ease, border-color 0.15s ease, transform 0.15s ease;
+  font-family: var(--font-sans);
+  white-space: nowrap;
+  line-height: 1;
+  min-height: 30px;
+  display: inline-flex;
+  align-items: center;
+}
+
+.sp-opt:hover {
+  background: var(--btn-icon-hover);
+  color: var(--text-primary);
+  border-color: var(--border-hover);
+}
+
+.sp-opt:active {
+  transform: scale(0.97);
+}
+
+/* Active = same inversion as .btn-text:hover */
+.sp-opt.active {
+  background: var(--text-primary);
+  color: var(--bg-primary);
+  border-color: var(--text-primary);
+}
+
+/* ── Voice select — uses global select styles, no override needed ─ */
+.sp-select {
+  width: 100%;
+  /* global select rules apply; just ensure full width */
+}
+
+.sp-number {
+  width: 100%;
+  background: transparent;
+  color: var(--text-primary);
+  border: 1px solid var(--border-color);
+  border-radius: var(--radius-sm);
+  padding: 0.4rem 0.7rem;
+  font-family: var(--font-sans);
+  font-size: 0.82rem;
+}
+
+/* ── Speed slider row ─────────────────────────────────── */
+.sp-slider-wrap {
+  flex: 1;
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+}
+
+.sp-range {
+  flex: 1;
+  height: 3px;
+  appearance: none;
+  -webkit-appearance: none;
+  background: var(--range-track);
+  border-radius: var(--radius-full);
+  cursor: pointer;
+  outline: none;
+}
+
+.sp-range::-webkit-slider-thumb {
+  -webkit-appearance: none;
+  width: 16px;
+  height: 16px;
+  background: var(--text-primary);
+  border: 2.5px solid var(--bg-popover);
+  border-radius: 50%;
+  cursor: pointer;
+  box-shadow: 0 0 0 1px var(--border-hover);
+  transition: transform 0.15s ease;
+}
+
+.sp-range::-webkit-slider-thumb:hover {
+  transform: scale(1.2);
+}
+
+.sp-range-val {
+  font-family: var(--font-sans);
+  font-size: 0.72rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--text-secondary);
+  min-width: 28px;
+  text-align: right;
+  font-variant-numeric: tabular-nums;
+}
+
+/* ════ TOC / Bookmarks popovers ════ */
+.bookmarks-popover,
+.toc-popover {
+  position: absolute;
+  top: 68px;
+  right: 1.5rem;
+  z-index: 200;
+  width: 290px;
+  background: var(--bg-popover);
+  border: 1px solid var(--border-color);
+  border-radius: var(--radius-md);
+  box-shadow: var(--shadow-lg);
+  backdrop-filter: blur(20px);
+  -webkit-backdrop-filter: blur(20px);
+  animation: spEnter 0.2s cubic-bezier(0.16, 1, 0.3, 1) both;
+  padding: 1.25rem;
+}
+
+/* ── Legacy aliases (TOC/Bookmarks still use these) ──── */
+.settings-section-title {
+  font-family: var(--font-sans);
+  font-size: 0.6rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  color: var(--text-muted);
+  letter-spacing: 0.18em;
+  margin-bottom: 0.75rem;
+  display: block;
+}
+
+
+
+
+
+.toc-list {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  overflow-y: auto;
+  max-height: 52vh;
+}
+
+.toc-item {
+  font-family: var(--font-sans);
+  font-size: 0.9rem;
+  padding: 0.75rem 1rem;
+  border-radius: var(--radius-md);
+  color: var(--text-secondary);
+  cursor: pointer;
+  transition: var(--transition-fast);
+  border: 1px solid transparent;
+  line-height: 1.4;
+}
+
+.toc-item:hover {
+  background: var(--toc-hover);
+  color: var(--text-primary);
+}
+
+.toc-item.active {
+  color: var(--text-primary);
+  background: var(--toc-active);
+  border-color: var(--toc-active-border);
+  font-weight: 500;
+}
+
+/* ─── Selects & Inputs ───────────────────────────────── */
+select {
+  font-family: var(--font-sans);
+  background-color: var(--select-bg);
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='12' viewBox='0 0 24 24' fill='none' stroke='currentColor' stroke-opacity='0.45' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpolyline points='6 9 12 15 18 9'%3E%3C/polyline%3E%3C/svg%3E");
+  background-repeat: no-repeat;
+  background-position: right 1rem center;
+  background-size: 14px;
+  -webkit-appearance: none;
+  appearance: none;
+  border-radius: var(--radius-full);
+  border: 1px solid var(--border-color);
+  color: var(--text-primary);
+  padding: 0.7rem 2.5rem 0.7rem 1.1rem;
+  cursor: pointer;
+  transition: var(--transition-fast);
+  font-size: 0.875rem;
+  color-scheme: var(--color-scheme);
+  width: 100%;
+}
+
+select:hover {
+  border-color: var(--border-hover);
+  background-color: var(--select-bg-hover);
+}
+
+select:focus {
+  outline: none;
+  border-color: var(--border-hover);
+  box-shadow: 0 0 0 3px var(--bg-input);
+}
+
+select option {
+  background-color: var(--select-option-bg);
+  color: var(--select-option-color);
+}
+
+select option:disabled {
+  color: var(--select-disabled-color);
+}
+
+input[type="range"] {
+  -webkit-appearance: none;
+  appearance: none;
+  width: 100%;
+  background: transparent;
+  height: 3px;
+  cursor: pointer;
+}
+
+input[type="range"]::-webkit-slider-runnable-track {
+  width: 100%;
+  height: 2px;
+  background: var(--range-track);
+  border-radius: var(--radius-full);
+}
+
+input[type="range"]::-webkit-slider-thumb {
+  -webkit-appearance: none;
+  appearance: none;
+  height: 14px;
+  width: 14px;
+  margin-top: -6px;
+  border-radius: 50%;
+  background: var(--text-primary);
+  cursor: pointer;
+  transition: transform 0.15s ease, box-shadow 0.15s ease;
+}
+
+input[type="range"]::-webkit-slider-thumb:hover {
+  transform: scale(1.25);
+  box-shadow: 0 0 0 4px var(--bg-input);
+}
+
+input[type="number"] {
+  font-family: var(--font-sans);
+  border-radius: var(--radius-md);
+  border: 1px solid var(--border-color);
+  padding: 0.65rem 1rem;
+  background: var(--bg-input);
+  color: var(--text-primary);
+  font-size: 0.875rem;
+  transition: var(--transition-fast);
+  width: 100%;
+}
+
+input[type="number"]:focus {
+  outline: none;
+  border-color: var(--border-hover);
+}
+
+/* ─── Reading progress bar ───────────────────────────── */
+.highlight,
+.book-page p.highlight,
+.book-page h1.highlight,
+.book-page h2.highlight,
+.book-page h3.highlight {
+  background-color: var(--highlight-color) !important;
+  color: #000000 !important;
+  border-radius: var(--radius-xs) !important;
+  transition: background-color 0.35s ease, color 0.35s ease !important;
+  padding: 0.25rem 0.5rem !important;
+  box-shadow: 0 0 0 4px var(--highlight-color) !important;
+  margin-left: -0.5rem !important;
+  margin-right: -0.5rem !important;
+}
+
+/* Utility */
+a,
+button,
+[role="button"] {
+  cursor: pointer;
+}
+
+/* Focus ring for keyboard users */
+:focus-visible {
+  outline: 2px solid var(--border-hover);
+  outline-offset: 2px;
+}

App/frontend/src/main.jsx

@@ -0,0 +1,10 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import './index.css'
+import App from './App.jsx'
+
+createRoot(document.getElementById('root')).render(
+  <StrictMode>
+    <App />
+  </StrictMode>,
+)