npm - @olives/devos - Versions diffs - 2.1.0 - Mend

@olives/devos 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (741) hide show

package/.agents/skills/shadcn-ui/resources/customization-guide.md ADDED Viewed

@@ -0,0 +1,516 @@
+# shadcn/ui Customization Guide
+Learn how to customize shadcn/ui components to match your brand and design requirements.
+## Theming Approach
+shadcn/ui uses a CSS variable-based theming system, making it easy to customize colors, spacing, and other design tokens globally.
+## Color Customization
+### Understanding the Color System
+shadcn/ui uses HSL color values stored as CSS variables. Each color has a base value and a foreground variant for text/content that appears on top of it.
+**Base Color Variables** (in `globals.css`):
+```css
+:root {
+  --background: 0 0% 100%;        /* Page background */
+  --foreground: 222.2 84% 4.9%;   /* Primary text color */
+  --primary: 221.2 83.2% 53.3%;   /* Primary brand color */
+  --primary-foreground: 210 40% 98%; /* Text on primary */
+  --secondary: 210 40% 96.1%;     /* Secondary actions */
+  --accent: 210 40% 96.1%;        /* Accent highlights */
+  --muted: 210 40% 96.1%;         /* Muted backgrounds */
+  --destructive: 0 84.2% 60.2%;   /* Error/danger */
+  --border: 214.3 31.8% 91.4%;    /* Border colors */
+  --input: 214.3 31.8% 91.4%;     /* Input borders */
+  --ring: 221.2 83.2% 53.3%;      /* Focus rings */
+}
+```
+### Changing Brand Colors
+To match your brand, update the primary color:
+```css
+:root {
+  /* Original blue */
+  --primary: 221.2 83.2% 53.3%;
+  /* Change to brand purple */
+  --primary: 270 91% 65%;
+  /* Adjust foreground for contrast */
+  --primary-foreground: 0 0% 100%;
+}
+```
+**HSL Format**: `hue saturation lightness`
+- Hue: 0-360 (color wheel position)
+- Saturation: 0-100% (color intensity)
+- Lightness: 0-100% (brightness)
+### Tools for Color Selection
+1. **HSL Color Picker**: https://hslpicker.com/
+2. **Shadcn Theme Generator**: https://ui.shadcn.com/themes
+3. **Coolors**: https://coolors.co/ (generates palettes)
+### Creating a Color Scheme
+Start with your primary brand color, then derive other colors:
+```css
+:root {
+  /* 1. Primary brand color */
+  --primary: 230 90% 60%;
+  --primary-foreground: 0 0% 100%;
+  /* 2. Lighter variant for secondary */
+  --secondary: 230 30% 95%;
+  --secondary-foreground: 230 90% 30%;
+  /* 3. Subtle accent (shift hue slightly) */
+  --accent: 200 90% 60%;
+  --accent-foreground: 0 0% 100%;
+  /* 4. Muted backgrounds (low saturation) */
+  --muted: 230 20% 96%;
+  --muted-foreground: 230 20% 40%;
+  /* 5. Keep destructive red-based */
+  --destructive: 0 84% 60%;
+  --destructive-foreground: 0 0% 100%;
+}
+```
+## Dark Mode
+### Setting Up Dark Mode
+shadcn/ui includes dark mode support out of the box. Add dark mode colors:
+```css
+.dark {
+  --background: 222.2 84% 4.9%;
+  --foreground: 210 40% 98%;
+  --primary: 221.2 83.2% 53.3%;
+  --primary-foreground: 210 40% 98%;
+  /* ... all color variables */
+}
+```
+### Toggle Dark Mode
+**Next.js with next-themes**:
+```bash
+npm install next-themes
+```
+```tsx
+// app/providers.tsx
+"use client"
+import { ThemeProvider } from "next-themes"
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
+      {children}
+    </ThemeProvider>
+  )
+}
+// app/layout.tsx
+import { Providers } from "./providers"
+export default function RootLayout({ children }) {
+  return (
+    <html suppressHydrationWarning>
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  )
+}
+// components/theme-toggle.tsx
+"use client"
+import { Moon, Sun } from "lucide-react"
+import { useTheme } from "next-themes"
+import { Button } from "@/components/ui/button"
+export function ThemeToggle() {
+  const { setTheme, theme } = useTheme()
+  return (
+    <Button
+      variant="ghost"
+      size="icon"
+      onClick={() => setTheme(theme === "light" ? "dark" : "light")}
+    >
+      <Sun className="h-5 w-5 rotate-0 scale-100 transition-all dark:-rotate-90 dark:scale-0" />
+      <Moon className="absolute h-5 w-5 rotate-90 scale-0 transition-all dark:rotate-0 dark:scale-100" />
+      <span className="sr-only">Toggle theme</span>
+    </Button>
+  )
+}
+```
+## Component Customization
+### Using Variants
+shadcn/ui components use `class-variance-authority` (cva) for variants. Example from Button:
+```typescript
+// components/ui/button.tsx
+import { cva, type VariantProps } from "class-variance-authority"
+const buttonVariants = cva(
+  "inline-flex items-center justify-center rounded-md text-sm font-medium",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground hover:bg-primary/90",
+        destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
+        outline: "border border-input bg-background hover:bg-accent",
+        ghost: "hover:bg-accent hover:text-accent-foreground",
+        link: "text-primary underline-offset-4 hover:underline",
+      },
+      size: {
+        default: "h-10 px-4 py-2",
+        sm: "h-9 rounded-md px-3",
+        lg: "h-11 rounded-md px-8",
+        icon: "h-10 w-10",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+)
+```
+### Adding Custom Variants
+To add a new variant, edit the component file in `components/ui/`:
+```typescript
+// Add new "success" variant to button
+const buttonVariants = cva(
+  "...",
+  {
+    variants: {
+      variant: {
+        default: "...",
+        destructive: "...",
+        // Add new variant
+        success: "bg-green-600 text-white hover:bg-green-700",
+      },
+      // Add new size
+      size: {
+        default: "...",
+        xl: "h-12 rounded-md px-10 text-base",
+      },
+    },
+  }
+)
+// Update TypeScript interface
+export interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {
+  asChild?: boolean
+}
+```
+Usage:
+```tsx
+<Button variant="success" size="xl">Save Changes</Button>
+```
+### Creating Composite Components
+Don't modify `components/ui/` directly. Instead, create wrapper components:
+```tsx
+// components/loading-button.tsx
+import { Button, ButtonProps } from "@/components/ui/button"
+import { Loader2 } from "lucide-react"
+interface LoadingButtonProps extends ButtonProps {
+  loading?: boolean
+}
+export function LoadingButton({
+  loading,
+  children,
+  disabled,
+  ...props
+}: LoadingButtonProps) {
+  return (
+    <Button disabled={loading || disabled} {...props}>
+      {loading && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
+      {children}
+    </Button>
+  )
+}
+```
+## Typography Customization
+### Font Family
+Update `tailwind.config.js`:
+```javascript
+module.exports = {
+  theme: {
+    extend: {
+      fontFamily: {
+        sans: ['Inter', 'system-ui', 'sans-serif'],
+        heading: ['Poppins', 'system-ui', 'sans-serif'],
+        mono: ['Fira Code', 'monospace'],
+      },
+    },
+  },
+}
+```
+Import fonts in your layout:
+```tsx
+// app/layout.tsx
+import { Inter, Poppins } from 'next/font/google'
+const inter = Inter({ subsets: ['latin'], variable: '--font-sans' })
+const poppins = Poppins({
+  weight: ['600', '700'],
+  subsets: ['latin'],
+  variable: '--font-heading',
+})
+export default function RootLayout({ children }) {
+  return (
+    <html className={`${inter.variable} ${poppins.variable}`}>
+      <body className="font-sans">{children}</body>
+    </html>
+  )
+}
+```
+Use in components:
+```tsx
+<h1 className="font-heading text-3xl">Heading</h1>
+<p className="font-sans">Body text</p>
+```
+### Font Sizes
+Extend Tailwind's font scale:
+```javascript
+// tailwind.config.js
+module.exports = {
+  theme: {
+    extend: {
+      fontSize: {
+        'xs': '0.75rem',     // 12px
+        'sm': '0.875rem',    // 14px
+        'base': '1rem',      // 16px
+        'lg': '1.125rem',    // 18px
+        'xl': '1.25rem',     // 20px
+        '2xl': '1.5rem',     // 24px
+        '3xl': '1.875rem',   // 30px
+        '4xl': '2.25rem',    // 36px
+        '5xl': '3rem',       // 48px
+        '6xl': '3.75rem',    // 60px
+        '7xl': '4.5rem',     // 72px
+      },
+    },
+  },
+}
+```
+## Spacing & Layout
+### Border Radius
+Customize roundedness globally:
+```css
+/* globals.css */
+:root {
+  --radius: 0.5rem;  /* Default (8px) */
+  /* More rounded */
+  --radius: 1rem;    /* 16px */
+  /* Sharp edges */
+  --radius: 0;       /* No rounding */
+  /* Very rounded */
+  --radius: 1.5rem;  /* 24px */
+}
+```
+This affects all components using `rounded-lg`, `rounded-md`, `rounded-sm`.
+### Custom Spacing
+Extend Tailwind's spacing scale:
+```javascript
+// tailwind.config.js
+module.exports = {
+  theme: {
+    extend: {
+      spacing: {
+        '72': '18rem',
+        '84': '21rem',
+        '96': '24rem',
+      },
+    },
+  },
+}
+```
+## Animation Customization
+### Adjusting Existing Animations
+```javascript
+// tailwind.config.js
+module.exports = {
+  theme: {
+    extend: {
+      keyframes: {
+        // Make accordion faster
+        "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.15s ease-out", // Faster
+        "accordion-up": "accordion-up 0.15s ease-out",
+      },
+    },
+  },
+}
+```
+### Adding New Animations
+```javascript
+// tailwind.config.js
+module.exports = {
+  theme: {
+    extend: {
+      keyframes: {
+        "fade-in": {
+          "0%": { opacity: 0 },
+          "100%": { opacity: 1 },
+        },
+        "slide-in-bottom": {
+          "0%": { transform: "translateY(100%)" },
+          "100%": { transform: "translateY(0)" },
+        },
+      },
+      animation: {
+        "fade-in": "fade-in 0.3s ease-out",
+        "slide-in-bottom": "slide-in-bottom 0.3s ease-out",
+      },
+    },
+  },
+}
+```
+Use in components:
+```tsx
+<div className="animate-fade-in">Content</div>
+```
+## Advanced Customization
+### Creating a Design System
+Structure your customizations:
+```
+src/
+├── styles/
+│   ├── globals.css          # CSS variables & base styles
+│   ├── themes/
+│   │   ├── default.css      # Default theme
+│   │   └── brand.css        # Brand-specific overrides
+│   └── components/
+│       └── custom.css       # Component-specific styles
+├── lib/
+│   └── design-tokens.ts     # Shared constants
+└── components/
+    ├── ui/                  # shadcn components (don't modify)
+    └── custom/              # Your wrapper components
+```
+### Design Tokens File
+```typescript
+// lib/design-tokens.ts
+export const designTokens = {
+  colors: {
+    brand: {
+      primary: 'hsl(230, 90%, 60%)',
+      secondary: 'hsl(230, 30%, 95%)',
+    },
+  },
+  spacing: {
+    section: '5rem',
+    card: '1.5rem',
+  },
+  radius: {
+    card: '1rem',
+    button: '0.5rem',
+  },
+  typography: {
+    h1: 'text-5xl font-heading font-bold',
+    h2: 'text-4xl font-heading font-semibold',
+    h3: 'text-3xl font-heading font-semibold',
+    body: 'text-base font-sans',
+    small: 'text-sm text-muted-foreground',
+  },
+} as const
+```
+Use in components:
+```tsx
+import { designTokens } from "@/lib/design-tokens"
+<h1 className={designTokens.typography.h1}>Title</h1>
+```
+## Best Practices
+1. **Don't modify `components/ui/` files directly**: Create wrapper components instead
+2. **Use CSS variables for theming**: Easier to maintain and switch themes
+3. **Leverage Tailwind's `extend`**: Don't replace defaults, extend them
+4. **Keep variants in component files**: Co-locate variant logic with components
+5. **Test dark mode**: Ensure all customizations work in both themes
+6. **Document custom variants**: Add comments for custom additions
+7. **Use consistent spacing**: Stick to Tailwind's spacing scale
+8. **Maintain accessibility**: Don't sacrifice contrast for aesthetics
+## Resources
+- [Tailwind CSS Customization](https://tailwindcss.com/docs/theme)
+- [CVA Documentation](https://cva.style/docs)
+- [Radix UI Theming](https://www.radix-ui.com/themes/docs/theme/overview)
+- [HSL Color Theory](https://www.w3.org/TR/css-color-3/#hsl-color)