[FEATURE] Multi-flavored Catppuccin theme support [Size: M-L, Priority...

[devwif]

[FEATURE] Multi-flavored Catppuccin Theme Support

---

🚀 Problem Statement

The WebTUI project currently supports basic theming but lacks multi-flavored Catppuccin theme support — an iconic, beloved color palette among developer communities. Adding this feature will:

• Differentiate WebTUI with a vibrant, community-recognized theme.
• Enhance brand recognition and appeal to niche users who value aesthetic terminal-like UI.
• Provide a flexible, extensible theming foundation for future contributions.

This feature is medium-to-large in scope and should be prioritized as a "Should" to boost market impact and community engagement.

---

🧠 Technical Context

• Current State: WebTUI is a modular CSS terminal-like UI library built with Astro and TypeScript.
• Existing Theming: Basic theming capability exists but lacks multi-flavored theme variants.
• Target Theme: Catppuccin is a popular pastel color palette with multiple "flavors" such as Mocha, Latte, Frappe, Macchiato, etc.
• Tech Stack: Astro framework, TypeScript, and @biomejs/biome for linting/formatting.
• Repository Size: ~2.7 MB, 8 open issues.
• Current Challenges: Limited theming reduces appeal; lack of differentiated theme options limits customization and user satisfaction.

---

🛠 Detailed Implementation Steps

1. Research & Analysis

   • Review the official Catppuccin theme specifications and palettes: https://github.com/catppuccin/catppuccin
   • Analyze popular implementations (VSCode, Neovim, etc.) for flavor structure and usage patterns.
   • Identify which flavors will be supported initially (recommend starting with Mocha, Latte, Frappe, Macchiato).

2. Design User Experience & Technical Architecture

   • Plan how flavors will be selected/applied in the WebTUI components:
     • Via a global theme context/provider.
     • Per-component overrides (optional).
   • Define the theme data structure:

     interface CatppuccinFlavor {
       background: string;
       foreground: string;
       accent: string;
       // ...other palette colors
     }

   • Design API for theme switching, e.g., useTheme('mocha') or <ThemeProvider flavor="mocha">.

3. Development Roadmap

   • Break down into milestones:
     • Theme data integration.
     • Theme provider/context implementation.
     • Component style updates to consume theme variables.
     • Create storybook/examples showcasing flavors.
     • Accessibility and contrast validations per flavor.
     • Documentation & testing.

4. Implement MVP Version

   • Add Catppuccin flavor palettes as JSON or TS constants.
   • Implement ThemeProvider and hooks for flavor switching.
   • Update core components to support dynamic theme properties.
   • Add flavor switcher UI demo in example app.
   • Ensure styles are optimized and don’t cause performance regressions.

5. Gather Feedback & Iterate

   • Open beta release for internal testers or early adopters.
   • Collect UX feedback and accessibility reports.
   • Refine color contrasts and usability.
   • Optimize for light/dark mode toggling if applicable.

---

🔧 Technical Specifications

• Theme Data:

  • Store Catppuccin flavors as strongly typed objects.
  • Support CSS variables or inline style injection for runtime switching.

• API:

  • <ThemeProvider flavor="latte"> component wrapping the app.
  • useTheme() hook returning current flavor and setter method.
  • Flavor switching triggers CSS variable updates or className toggling.

• Components:

  • Update all UI components (buttons, inputs, dialogs, tooltips, etc.) to consume theme tokens.
  • Ensure fallback to default theme if flavor is missing.

• Accessibility:

  • Validate color contrast meets WCAG AA standards for text and UI elements.
  • Provide overrides or warnings if any flavor fails accessibility tests.

• Performance:

  • Use CSS variables or lightweight context to avoid re-render bottlenecks.
  • Lazy-load theme palettes if necessary.

---

✅ Acceptance Criteria

• Catppuccin flavor palettes (Mocha, Latte, Frappe, Macchiato) integrated as theme data.
• ThemeProvider component implemented with flavor selection support.
• Core components consume theme tokens and reflect active flavor.
• Example app/demo includes flavor switcher UI.
• Accessibility contrast validation passed for all flavors.
• Unit and integration tests covering theme switching and palette application.
• Documentation updated with theming guide and Catppuccin flavor usage.
• User feedback collected and incorporated for final tweaks.

---

🧪 Testing Requirements

• Unit tests for:
  • ThemeProvider logic and flavor switching.
  • Hook API correctness.
• Integration tests for:
  • Components rendering correct colors per flavor.
  • UI behavior with dynamic theme changes.
• Accessibility audits using axe-core or similar tools.
• Visual regression testing with screenshots for each flavor.
• Manual testing on different devices and browsers.

---

📚 Documentation Needs

• Update /docs/theming.md with:
  • Overview of multi-flavored Catppuccin themes.
  • How to use ThemeProvider and switch flavors.
  • List and description of supported flavors.
  • Guidance on creating custom flavors.
• Add flavor switcher demo in /examples folder.
• Update README with new feature highlights and usage instructions.

---

⚠️ Potential Challenges

• Maintaining accessibility compliance across pastel-heavy color palettes.
• Ensuring minimal performance overhead with dynamic theming.
• Handling legacy components that may have hardcoded colors.
• Coordinating flavor updates if the Catppuccin palette evolves upstream.
• Balancing theme flexibility with API simplicity.

---

🔗 Resources & References

• Official Catppuccin repo & palettes: https://github.com/catppuccin/catppuccin
• Astro theming best practices: https://docs.astro.build/en/guides/styling/#theming
• React Context API (for theme provider): https://reactjs.org/docs/context.html
• WCAG color contrast guidelines: https://www.w3.org/WAI/WCAG21/quickref/#contrast-minimum
• axe-core accessibility testing: https://www.deque.com/axe/
• Example multi-flavor theme implementation (VSCode): https://github.com/catppuccin/vscode

---

Let’s brew this Catppuccin-themed WebTUI and enchant our users with sublime pastel vibes! ☕✨

---

Checklist for assignees:

• Research and finalize Catppuccin flavors to support
• Design theme data structure and API
• Implement ThemeProvider and hooks
• Update components for theme consumption
• Build demo UI flavor switcher
• Write and run tests (unit, integration, accessibility)
• Update documentation and examples
• Collect and incorporate user feedback

---

If you have questions or need pairing, ping me! Together, we’ll make this feature a delightful reality.