moai-adk 0.25.4__py3-none-any.whl → 0.32.8__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-domain-uiux/modules/theming-system.md

@@ -0,0 +1,373 @@
+name: moai-library-shadcn-theming
+description: shadcn/ui theme system and design token customization
+
+## Theme System Implementation
+
+### Advanced Theme Provider
+
+```typescript
+// Advanced theme system with CSS variables and dark mode
+import { createContext, useContext, useEffect, useState } from "react";
+
+type Theme = "dark" | "light" | "system";
+
+interface ThemeProviderProps {
+ children: React.ReactNode;
+ defaultTheme?: Theme;
+ storageKey?: string;
+ attribute?: string;
+ enableSystem?: boolean;
+}
+
+interface ThemeProviderState {
+ theme: Theme;
+ setTheme: (theme: Theme) => void;
+}
+
+const ThemeProviderContext = createContext<ThemeProviderState | undefined>(undefined);
+
+export function ThemeProvider({
+ children,
+ defaultTheme = "system",
+ storageKey = "ui-theme",
+ attribute = "class",
+ enableSystem = true,
+ ...props
+}: ThemeProviderProps) {
+ const [theme, setTheme] = useState<Theme>(() => {
+ if (typeof window !== "undefined") {
+ return (localStorage.getItem(storageKey) as Theme) || defaultTheme;
+ }
+ return defaultTheme;
+ });
+
+ useEffect(() => {
+ const root = window.document.documentElement;
+
+ root.classList.remove("light", "dark");
+
+ if (theme === "system" && enableSystem) {
+ const systemTheme = window.matchMedia("(prefers-color-scheme: dark)")
+ .matches
+ ? "dark"
+ : "light";
+
+ root.classList.add(systemTheme);
+ return;
+ }
+
+ root.classList.add(theme);
+ }, [theme, enableSystem, attribute]);
+
+ const value = {
+ theme,
+ setTheme: (theme: Theme) => {
+ localStorage.setItem(storageKey, theme);
+ setTheme(theme);
+ },
+ };
+
+ return (
+ <ThemeProviderContext.Provider {...props} value={value}>
+ {children}
+ </ThemeProviderContext.Provider>
+ );
+}
+
+export const useTheme = () => {
+ const context = useContext(ThemeProviderContext);
+
+ if (context === undefined)
+ throw new Error("useTheme must be used within a ThemeProvider");
+
+ return context;
+};
+```
+
+### Design Token Configuration
+
+```typescript
+// Theme configuration with design tokens
+export const theme = {
+ light: {
+ background: "hsl(0 0% 100%)",
+ foreground: "hsl(240 10% 3.9%)",
+ card: "hsl(0 0% 100%)",
+ cardForeground: "hsl(240 10% 3.9%)",
+ popover: "hsl(0 0% 100%)",
+ popoverForeground: "hsl(240 10% 3.9%)",
+ primary: "hsl(240 9% 10%)",
+ primaryForeground: "hsl(0 0% 98%)",
+ secondary: "hsl(240 4.8% 95.9%)",
+ secondaryForeground: "hsl(240 3.8% 46.1%)",
+ muted: "hsl(240 4.8% 95.9%)",
+ mutedForeground: "hsl(240 3.8% 46.1%)",
+ accent: "hsl(240 4.8% 95.9%)",
+ accentForeground: "hsl(240 5.9% 10%)",
+ destructive: "hsl(0 72.22% 50.59%)",
+ destructiveForeground: "hsl(0 0% 98%)",
+ border: "hsl(240 5.9% 90%)",
+ input: "hsl(240 5.9% 90%)",
+ ring: "hsl(240 5.9% 10%)",
+ },
+ dark: {
+ background: "hsl(240 10% 3.9%)",
+ foreground: "hsl(0 0% 98%)",
+ card: "hsl(240 10% 3.9%)",
+ cardForeground: "hsl(0 0% 98%)",
+ popover: "hsl(240 10% 3.9%)",
+ popoverForeground: "hsl(0 0% 98%)",
+ primary: "hsl(0 0% 98%)",
+ primaryForeground: "hsl(240 9% 10%)",
+ secondary: "hsl(240 3.7% 15.9%)",
+ secondaryForeground: "hsl(0 0% 98%)",
+ muted: "hsl(240 3.7% 15.9%)",
+ mutedForeground: "hsl(240 5% 64.9%)",
+ accent: "hsl(240 3.7% 15.9%)",
+ accentForeground: "hsl(0 0% 98%)",
+ destructive: "hsl(0 62.8% 30.6%)",
+ destructiveForeground: "hsl(0 0% 98%)",
+ border: "hsl(240 3.7% 15.9%)",
+ input: "hsl(240 3.7% 15.9%)",
+ ring: "hsl(240 4.9% 83.9%)",
+ },
+};
+
+// Apply theme CSS variables
+export function applyThemeCSS() {
+ const root = document.documentElement;
+ 
+ Object.entries(theme.light).forEach(([key, value]) => {
+ root.style.setProperty(`--${key}`, value);
+ });
+}
+```
+
+### CSS Variables in globals.css
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+ :root {
+ --background: 0 0% 100%;
+ --foreground: 240 10% 3.9%;
+ --card: 0 0% 100%;
+ --card-foreground: 240 10% 3.9%;
+ --popover: 0 0% 100%;
+ --popover-foreground: 240 10% 3.9%;
+ --primary: 240 9% 10%;
+ --primary-foreground: 0 0% 98%;
+ --secondary: 240 4.8% 95.9%;
+ --secondary-foreground: 240 3.8% 46.1%;
+ --muted: 240 4.8% 95.9%;
+ --muted-foreground: 240 3.8% 46.1%;
+ --accent: 240 4.8% 95.9%;
+ --accent-foreground: 240 5.9% 10%;
+ --destructive: 0 72.22% 50.59%;
+ --destructive-foreground: 0 0% 98%;
+ --border: 240 5.9% 90%;
+ --input: 240 5.9% 90%;
+ --ring: 240 5.9% 10%;
+ --radius: 0.5rem;
+ }
+
+ .dark {
+ --background: 240 10% 3.9%;
+ --foreground: 0 0% 98%;
+ --card: 240 10% 3.9%;
+ --card-foreground: 0 0% 98%;
+ --popover: 240 10% 3.9%;
+ --popover-foreground: 0 0% 98%;
+ --primary: 0 0% 98%;
+ --primary-foreground: 240 9% 10%;
+ --secondary: 240 3.7% 15.9%;
+ --secondary-foreground: 0 0% 98%;
+ --muted: 240 3.7% 15.9%;
+ --muted-foreground: 240 5% 64.9%;
+ --accent: 240 3.7% 15.9%;
+ --accent-foreground: 0 0% 98%;
+ --destructive: 0 62.8% 30.6%;
+ --destructive-foreground: 0 0% 98%;
+ --border: 240 3.7% 15.9%;
+ --input: 240 3.7% 15.9%;
+ --ring: 240 4.9% 83.9%;
+ }
+}
+
+@layer base {
+ * {
+ @apply border-border;
+ }
+ body {
+ @apply bg-background text-foreground;
+ }
+}
+```
+
+### Custom Brand Theme
+
+```typescript
+// Create custom brand theme
+export function createBrandTheme(brandColors: {
+ primary: string;
+ secondary: string;
+ accent: string;
+}) {
+ return {
+ light: {
+ ...theme.light,
+ primary: brandColors.primary,
+ secondary: brandColors.secondary,
+ accent: brandColors.accent,
+ },
+ dark: {
+ ...theme.dark,
+ primary: brandColors.primary,
+ secondary: brandColors.secondary,
+ accent: brandColors.accent,
+ },
+ };
+}
+
+// Apply custom brand theme
+export function applyBrandTheme(brandTheme: typeof theme) {
+ const root = document.documentElement;
+ const currentTheme = root.classList.contains("dark") ? "dark" : "light";
+ 
+ Object.entries(brandTheme[currentTheme]).forEach(([key, value]) => {
+ root.style.setProperty(`--${key}`, value);
+ });
+}
+```
+
+### Theme Toggle Component
+
+```typescript
+// Theme toggle component
+import { Moon, Sun } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import {
+ DropdownMenu,
+ DropdownMenuContent,
+ DropdownMenuItem,
+ DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import { useTheme } from "@/components/theme-provider";
+
+export function ThemeToggle() {
+ const { setTheme } = useTheme();
+
+ return (
+ <DropdownMenu>
+ <DropdownMenuTrigger asChild>
+ <Button variant="outline" size="icon">
+ <Sun className="h-[1.2rem] w-[1.2rem] rotate-0 scale-100 transition-all dark:-rotate-90 dark:scale-0" />
+ <Moon className="absolute h-[1.2rem] w-[1.2rem] rotate-90 scale-0 transition-all dark:rotate-0 dark:scale-100" />
+ <span className="sr-only">Toggle theme</span>
+ </Button>
+ </DropdownMenuTrigger>
+ <DropdownMenuContent align="end">
+ <DropdownMenuItem onClick={() => setTheme("light")}>
+ Light
+ </DropdownMenuItem>
+ <DropdownMenuItem onClick={() => setTheme("dark")}>
+ Dark
+ </DropdownMenuItem>
+ <DropdownMenuItem onClick={() => setTheme("system")}>
+ System
+ </DropdownMenuItem>
+ </DropdownMenuContent>
+ </DropdownMenu>
+ );
+}
+```
+
+### Tailwind Configuration
+
+```javascript
+// tailwind.config.js
+/ @type {import('tailwindcss').Config} */
+module.exports = {
+ darkMode: ["class"],
+ content: [
+ './pages//*.{ts,tsx}',
+ './components//*.{ts,tsx}',
+ './app//*.{ts,tsx}',
+ './src//*.{ts,tsx}',
+ ],
+ theme: {
+ container: {
+ center: true,
+ padding: "2rem",
+ screens: {
+ "2xl": "1400px",
+ },
+ },
+ extend: {
+ colors: {
+ border: "hsl(var(--border))",
+ input: "hsl(var(--input))",
+ ring: "hsl(var(--ring))",
+ background: "hsl(var(--background))",
+ foreground: "hsl(var(--foreground))",
+ primary: {
+ DEFAULT: "hsl(var(--primary))",
+ foreground: "hsl(var(--primary-foreground))",
+ },
+ secondary: {
+ DEFAULT: "hsl(var(--secondary))",
+ foreground: "hsl(var(--secondary-foreground))",
+ },
+ destructive: {
+ DEFAULT: "hsl(var(--destructive))",
+ foreground: "hsl(var(--destructive-foreground))",
+ },
+ muted: {
+ DEFAULT: "hsl(var(--muted))",
+ foreground: "hsl(var(--muted-foreground))",
+ },
+ accent: {
+ DEFAULT: "hsl(var(--accent))",
+ foreground: "hsl(var(--accent-foreground))",
+ },
+ popover: {
+ DEFAULT: "hsl(var(--popover))",
+ foreground: "hsl(var(--popover-foreground))",
+ },
+ card: {
+ DEFAULT: "hsl(var(--card))",
+ foreground: "hsl(var(--card-foreground))",
+ },
+ },
+ borderRadius: {
+ lg: "var(--radius)",
+ md: "calc(var(--radius) - 2px)",
+ sm: "calc(var(--radius) - 4px)",
+ },
+ keyframes: {
+ "accordion-down": {
+ from: { height: 0 },
+ to: { height: "var(--radix-accordion-content-height)" },
+ },
+ "accordion-up": {
+ from: { height: "var(--radix-accordion-content-height)" },
+ to: { height: 0 },
+ },
+ },
+ animation: {
+ "accordion-down": "accordion-down 0.2s ease-out",
+ "accordion-up": "accordion-up 0.2s ease-out",
+ },
+ },
+ },
+ plugins: [require("tailwindcss-animate")],
+}
+```
+
+---
+
+Last Updated: 2025-11-26
+Related: [Main Skill](../SKILL.md), [Component Architecture](component-architecture.md)

moai_adk/templates/.claude/skills/moai-domain-uiux/reference.md

@@ -0,0 +1,243 @@
+# External Documentation References
+
+Comprehensive collection of official documentation, specifications, and resources for UI/UX development.
+
+---
+
+## Design Systems & Tokens
+
+### W3C Design Tokens Community Group (DTCG)
+- Specification: https://designtokens.org
+- GitHub: https://github.com/design-tokens/community-group
+- Format Spec: https://tr.designtokens.org/format/
+- Latest Version: 2025.10 (first stable release)
+- Use Case: Design token architecture, multi-platform theming
+
+### Style Dictionary
+- Documentation: https://styledictionary.com
+- GitHub: https://github.com/amzn/style-dictionary
+- Version: 4.0+ (DTCG-compatible)
+- Use Case: Token transformation, platform-specific output
+
+---
+
+## Accessibility Standards
+
+### WCAG 2.2 (Web Content Accessibility Guidelines)
+- Quick Reference: https://www.w3.org/WAI/WCAG22/quickref/
+- Full Specification: https://www.w3.org/TR/WCAG22/
+- Understanding WCAG: https://www.w3.org/WAI/WCAG22/Understanding/
+- Level AA Requirements: https://www.w3.org/WAI/WCAG22/quickref/?currentsidebar=%23col_overview&levels=aaa
+- Use Case: Accessibility compliance, ARIA patterns, contrast ratios
+
+### axe DevTools
+- Website: https://www.deque.com/axe/devtools/
+- Documentation: https://www.deque.com/axe/devtools/documentation/
+- Chrome Extension: https://chrome.google.com/webstore/detail/axe-devtools/lhdoppojpmngadmnindnejefpokejbdd
+- Use Case: Automated accessibility testing
+
+### jest-axe
+- GitHub: https://github.com/nickcolley/jest-axe
+- npm: https://www.npmjs.com/package/jest-axe
+- Use Case: Accessibility testing in unit tests
+
+---
+
+## Component Libraries & Frameworks
+
+### React 19
+- Official Docs: https://react.dev
+- API Reference: https://react.dev/reference/react
+- Server Components: https://react.dev/reference/react/use-server
+- Latest Features: https://react.dev/blog
+- Use Case: Modern React patterns, Server Components, Suspense
+
+### Vue 3.5
+- Official Docs: https://vuejs.org
+- Composition API: https://vuejs.org/guide/extras/composition-api-faq.html
+- TypeScript: https://vuejs.org/guide/typescript/overview.html
+- Use Case: Vue component development, Composition API
+
+### shadcn/ui
+- Documentation: https://ui.shadcn.com/docs
+- Components: https://ui.shadcn.com/docs/components
+- Installation: https://ui.shadcn.com/docs/installation
+- GitHub: https://github.com/shadcn-ui/ui
+- Use Case: Copy-paste component library, Radix UI + Tailwind
+
+### Radix UI
+- Documentation: https://www.radix-ui.com
+- Primitives: https://www.radix-ui.com/primitives/docs/overview/introduction
+- Themes: https://www.radix-ui.com/themes/docs/overview/getting-started
+- Use Case: Unstyled accessible component primitives
+
+---
+
+## Styling & Theming
+
+### Tailwind CSS 3.4
+- Documentation: https://tailwindcss.com/docs
+- Configuration: https://tailwindcss.com/docs/configuration
+- Dark Mode: https://tailwindcss.com/docs/dark-mode
+- Customization: https://tailwindcss.com/docs/theme
+- Use Case: Utility-first CSS, design token integration
+
+### CSS Variables
+- MDN Reference: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
+- Browser Support: https://caniuse.com/css-variables
+- Use Case: Dynamic theming, design token implementation
+
+---
+
+## Icon Libraries
+
+### Lucide Icons
+- Website: https://lucide.dev
+- React: https://lucide.dev/guide/packages/lucide-react
+- Icons: https://lucide.dev/icons/
+- GitHub: https://github.com/lucide-icons/lucide
+- Bundle Size: ~30KB (1000+ icons)
+
+### React Icons
+- Website: https://react-icons.github.io/react-icons/
+- GitHub: https://github.com/react-icons/react-icons
+- Icons: 35,000+ icons from multiple libraries
+- Use Case: Multi-library support, modular imports
+
+### Tabler Icons
+- Website: https://tabler-icons.io
+- React: https://tabler-icons.io/docs/icons/react
+- GitHub: https://github.com/tabler/tabler-icons
+- Icons: 5900+ icons (dashboard optimized)
+
+### Iconify
+- Website: https://iconify.design
+- React: https://docs.iconify.design/icon-components/react/
+- Icon Sets: https://icon-sets.iconify.design
+- Icons: 200,000+ icons (CDN-based)
+
+### Heroicons
+- Website: https://heroicons.com
+- GitHub: https://github.com/tailwindlabs/heroicons
+- React: https://github.com/tailwindlabs/heroicons#react
+- Icons: 300+ icons (official Tailwind CSS icons)
+
+### Phosphor Icons
+- Website: https://phosphoricons.com
+- React: https://github.com/phosphor-icons/react
+- Icons: 800+ icons with 6 weight variations
+- Use Case: Weight flexibility (thin, light, regular, bold, fill, duotone)
+
+### Radix Icons
+- Website: https://www.radix-ui.com/icons
+- GitHub: https://github.com/radix-ui/icons
+- Icons: 150+ icons (precise 15x15px)
+- Bundle Size: ~5KB (minimal footprint)
+
+---
+
+## Design-to-Code Tools
+
+### Figma MCP
+- Documentation: https://help.figma.com/hc/en-us/articles/32132100833559
+- Server Setup: Desktop + Remote server modes
+- Use Case: Design token extraction, component code generation
+
+### Storybook 8.x
+- Documentation: https://storybook.js.org/docs
+- React: https://storybook.js.org/docs/react/get-started/introduction
+- Addons: https://storybook.js.org/docs/react/essentials/introduction
+- Use Case: Component documentation, visual testing
+
+### Chromatic
+- Website: https://www.chromatic.com
+- Documentation: https://www.chromatic.com/docs/
+- GitHub Action: https://github.com/chromaui/action
+- Use Case: Visual regression testing, Storybook integration
+
+---
+
+## Form Validation & State Management
+
+### React Hook Form
+- Documentation: https://react-hook-form.com
+- API: https://react-hook-form.com/api
+- Examples: https://react-hook-form.com/get-started
+- Use Case: Form state management, validation
+
+### Zod
+- Documentation: https://zod.dev
+- GitHub: https://github.com/colinhacks/zod
+- TypeScript Integration: https://zod.dev/?id=typescript
+- Use Case: Schema validation, type inference
+
+### TanStack Table
+- Documentation: https://tanstack.com/table/latest
+- React: https://tanstack.com/table/latest/docs/framework/react/react-table
+- Examples: https://tanstack.com/table/latest/docs/framework/react/examples
+- Use Case: Data tables, sorting, filtering, pagination
+
+---
+
+## TypeScript & Tooling
+
+### TypeScript 5.5
+- Documentation: https://www.typescriptlang.org/docs/
+- Handbook: https://www.typescriptlang.org/docs/handbook/intro.html
+- Release Notes: https://www.typescriptlang.org/docs/handbook/release-notes/overview.html
+- Use Case: Type safety, improved developer experience
+
+### class-variance-authority (CVA)
+- GitHub: https://github.com/joe-bell/cva
+- Documentation: https://cva.style/docs
+- Use Case: Variant management for components
+
+---
+
+## Testing
+
+### React Testing Library
+- Documentation: https://testing-library.com/docs/react-testing-library/intro/
+- API: https://testing-library.com/docs/react-testing-library/api
+- Examples: https://testing-library.com/docs/react-testing-library/example-intro
+- Use Case: Component testing, user-centric tests
+
+### Vitest
+- Documentation: https://vitest.dev
+- API: https://vitest.dev/api/
+- Configuration: https://vitest.dev/config/
+- Use Case: Fast unit testing, Vite integration
+
+---
+
+## Animation Libraries
+
+### Framer Motion
+- Documentation: https://www.framer.com/motion/
+- API: https://www.framer.com/motion/component/
+- Examples: https://www.framer.com/motion/examples/
+- Use Case: React animations, gestures
+
+---
+
+## Official Specifications
+
+- HTML Living Standard: https://html.spec.whatwg.org/multipage/
+- CSS Specifications: https://www.w3.org/Style/CSS/specs.en.html
+- WAI-ARIA: https://www.w3.org/TR/wai-aria-1.2/
+- ARIA Authoring Practices: https://www.w3.org/WAI/ARIA/apg/
+
+---
+
+## Community Resources
+
+- MDN Web Docs: https://developer.mozilla.org
+- Can I Use: https://caniuse.com
+- WebAIM: https://webaim.org
+- A11y Project: https://www.a11yproject.com
+- Inclusive Components: https://inclusive-components.design
+
+---
+
+Last Updated: 2025-11-26
+Status: Production Ready