@marianmeres/stuic 2.66.0 → 3.0.0

package/dist/components/Switch/README.md

@@ -107,6 +107,21 @@ A toggle switch component with size variants, keyboard support, and optional asy
 <Switch checked={false} disabled />
 ```
 
+## CSS Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--stuic-switch-accent` | `--stuic-accent` | Active (checked) color |
+
+### Example Override
+
+```css
+:root {
+  /* Green switches globally */
+  --stuic-switch-accent: var(--color-green-500);
+}
+```
+
 ## Keyboard Support
 
 - **Space**: Toggle switch

package/dist/components/Switch/Switch.svelte

@@ -9,7 +9,7 @@
 	export interface Props extends Omit<HTMLLabelAttributes, "children" | "onchange"> {
 		button?: HTMLButtonElement;
 		checked?: boolean;
-		size?: "xs" | "sm" | "md" | "lg" | "xl" | string;
+		size?: "sm" | "md" | "lg" | "xl" | string;
 		/** Form field name for the hidden checkbox */
 		name?: string;
 		class?: string;
@@ -42,7 +42,7 @@
 
 	let {
 		button = $bindable(),
-		size = "md",
+		size = "lg",
 		name,
 		class: classProp,
 		dotClass,
@@ -62,7 +62,6 @@
 
 	const _preset: any = {
 		size: {
-			xs: `h-4 w-7`,
 			sm: `h-5 w-9`,
 			md: `h-6 w-11`,
 			lg: `h-7 w-13`,
@@ -70,7 +69,6 @@
 		},
 		dot: {
 			size: {
-				xs: `size-2 data-[checked=true]:translate-x-4`,
 				sm: `size-3 data-[checked=true]:translate-x-5`,
 				md: `size-4 data-[checked=true]:translate-x-6`,
 				lg: `size-5 data-[checked=true]:translate-x-7`,
@@ -107,11 +105,10 @@
 
 		bg-neutral-400 dark:bg-neutral-400
 
-		data-[checked=true]:bg-switch-accent
-		dark:data-[checked=true]:bg-switch-accent-dark
+		data-[checked=true]:bg-(--stuic-switch-accent)
 
 		focus:outline-0
-		focus:ring-switch-accent/20 focus:dark:ring-switch-accent-dark/20
+		focus:ring-(--stuic-switch-accent)/20
 		focus:ring-4`,
 		size,
 		_preset.size[size],

package/dist/components/Switch/Switch.svelte.d.ts

@@ -4,7 +4,7 @@ import type { ValidateOptions, ValidationResult } from "../../actions/validate.s
 export interface Props extends Omit<HTMLLabelAttributes, "children" | "onchange"> {
     button?: HTMLButtonElement;
     checked?: boolean;
-    size?: "xs" | "sm" | "md" | "lg" | "xl" | string;
+    size?: "sm" | "md" | "lg" | "xl" | string;
     /** Form field name for the hidden checkbox */
     name?: string;
     class?: string;

package/dist/components/Switch/SwitchButton.svelte

@@ -76,12 +76,11 @@
 			disabled:!cursor-not-allowed disabled:!opacity-50 disabled:hover:brightness-100
 	
 			bg-neutral-400 dark:bg-neutral-400
-	
-			aria-[checked=true]:bg-switch-accent
-			dark:aria-[checked=true]:bg-switch-accent-dark
-	
+
+			aria-[checked=true]:bg-(--stuic-switch-accent)
+
 			focus:outline-0
-			focus:ring-switch-accent/20 focus:dark:ring-switch-accent-dark/20
+			focus:ring-(--stuic-switch-accent)/20
 			focus:ring-4`,
 		size,
 		_preset.size[size],

package/dist/components/Switch/index.css

@@ -1,5 +1,4 @@
-/* prettier-ignore */
-@theme inline {
-	--color-switch-accent: var(--color-switch-accent, var(--color-red-600));
-	--color-switch-accent-dark: var(--color-switch-accent-dark, var(--color-red-400));
+/* Switch component tokens */
+:root {
+	--stuic-switch-accent: var(--stuic-color-primary);
 }

package/dist/components/TabbedMenu/README.md

@@ -51,30 +51,35 @@ interface TabbedMenuItem {
 
 ## CSS Variables
 
+Customize the component's appearance using CSS custom properties:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `--stuic-tabbed-menu-tab-bg` | `--stuic-surface-sunken` | Tab background |
+| `--stuic-tabbed-menu-tab-text` | `--stuic-text-muted` | Tab text color |
+| `--stuic-tabbed-menu-tab-bg-active` | `--stuic-surface` | Active tab background |
+| `--stuic-tabbed-menu-tab-text-active` | `--stuic-text` | Active tab text color |
+| `--stuic-tabbed-menu-border` | `--stuic-border` | Border color |
+
+### Example Override
+
 ```css
-/* Tab button */
---color-tabbed-menu-tab-bg
---color-tabbed-menu-tab-bg-dark
---color-tabbed-menu-tab-text
---color-tabbed-menu-tab-text-dark
-
-/* Active tab */
---color-tabbed-menu-tab-active-bg
---color-tabbed-menu-tab-active-bg-dark
---color-tabbed-menu-tab-active-text
---color-tabbed-menu-tab-active-text-dark
-
-/* Border */
---color-tabbed-menu-border
---color-tabbed-menu-border-dark
-
-/* Sizing */
---tabbed-menu-border-radius: 0.5rem
---tabbed-menu-padding-x: 1rem
---tabbed-menu-padding-y: 0.5rem
---tabbed-menu-gap: 0.25rem
+:root {
+  --stuic-tabbed-menu-tab-bg-active: var(--color-indigo-100);
+  --stuic-tabbed-menu-tab-text-active: var(--color-indigo-900);
+}
 ```
 
+### Legacy Variables (Backwards Compatibility)
+
+The following legacy variable names still work as aliases:
+
+| Legacy Name | New Name |
+|-------------|----------|
+| `--color-tabbed-menu-tab-bg` | `--stuic-tabbed-menu-tab-bg` |
+| `--color-tabbed-menu-tab-active-bg` | `--stuic-tabbed-menu-tab-bg-active` |
+| `--color-tabbed-menu-border` | `--stuic-tabbed-menu-border` |
+
 ## Keyboard Navigation
 
 - `ArrowRight` / `ArrowDown` - Move to next tab

package/dist/components/TabbedMenu/TabbedMenu.svelte

@@ -69,9 +69,9 @@
 		px-4 py-2
 		rounded-t-md
 		border border-b-0
-		border-tabbed-menu-border dark:border-tabbed-menu-border-dark
-		bg-tabbed-menu-tab-bg dark:bg-tabbed-menu-tab-bg-dark
-		text-tabbed-menu-tab-text dark:text-tabbed-menu-tab-text-dark
+		border-(--stuic-tabbed-menu-border)
+		bg-(--stuic-tabbed-menu-tab-bg)
+		text-(--stuic-tabbed-menu-tab-text)
 		cursor-pointer
 		transition-colors duration-150
 		hover:brightness-105
@@ -82,8 +82,8 @@
 	// focus-visible:outline-2 focus-visible:outline-offset-2
 
 	const CLS_BUTTON_ACTIVE = `
-		bg-tabbed-menu-tab-active-bg dark:bg-tabbed-menu-tab-active-bg-dark
-		text-tabbed-menu-tab-active-text dark:text-tabbed-menu-tab-active-text-dark
+		bg-(--stuic-tabbed-menu-tab-bg-active)
+		text-(--stuic-tabbed-menu-tab-text-active)
 		font-medium
 	`;
 

package/dist/components/TabbedMenu/index.css

@@ -1,23 +1,8 @@
-/* prettier-ignore */
-@theme inline {
-	/* Tab button background */
-	--color-tabbed-menu-tab-bg: var(--color-tabbed-menu-tab-bg, var(--color-neutral-100));
-	--color-tabbed-menu-tab-bg-dark: var(--color-tabbed-menu-tab-bg-dark, var(--color-neutral-700));
-
-	/* Tab button text */
-	--color-tabbed-menu-tab-text: var(--color-tabbed-menu-tab-text, var(--color-neutral-600));
-	--color-tabbed-menu-tab-text-dark: var(--color-tabbed-menu-tab-text-dark, var(--color-neutral-300));
-
-	/* Active tab background */
-	--color-tabbed-menu-tab-active-bg: var(--color-tabbed-menu-tab-active-bg, var(--color-white));
-	--color-tabbed-menu-tab-active-bg-dark: var(--color-tabbed-menu-tab-active-bg-dark, var(--color-neutral-800));
-
-	/* Active tab text */
-	--color-tabbed-menu-tab-active-text: var(--color-tabbed-menu-tab-active-text, var(--color-neutral-900));
-	--color-tabbed-menu-tab-active-text-dark: var(--color-tabbed-menu-tab-active-text-dark, var(--color-white));
-
-	/* Border */
-	--color-tabbed-menu-border: var(--color-tabbed-menu-border, var(--color-neutral-300));
-	--color-tabbed-menu-border-dark: var(--color-tabbed-menu-border-dark, var(--color-neutral-600));
-
+/* TabbedMenu component tokens */
+:root {
+	--stuic-tabbed-menu-tab-bg: var(--stuic-color-muted);
+	--stuic-tabbed-menu-tab-text: var(--stuic-color-muted-foreground);
+	--stuic-tabbed-menu-tab-bg-active: var(--stuic-color-surface);
+	--stuic-tabbed-menu-tab-text-active: var(--stuic-color-foreground);
+	--stuic-tabbed-menu-border: var(--stuic-color-border);
 }

package/dist/components/ThemePreview/README.md

@@ -0,0 +1,289 @@
+# ThemePreview
+
+A comprehensive theme preview component that serves two purposes:
+
+1. **Visual Preview** - Shows all design tokens in action as a mini webpage layout
+2. **Reference Implementation** - Demonstrates theming best practices for creating components
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { ThemePreview } from '@marianmeres/stuic';
+</script>
+
+<ThemePreview />
+```
+
+### Compact Mode
+
+```svelte
+<ThemePreview compact showLabels={false} />
+```
+
+### Custom Sections
+
+```svelte
+<ThemePreview>
+  {#snippet header()}
+    <h1>My Custom Theme</h1>
+  {/snippet}
+
+  {#snippet sidebar()}
+    <nav>Custom navigation...</nav>
+  {/snippet}
+</ThemePreview>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `showLabels` | `boolean` | `true` | Show section labels |
+| `compact` | `boolean` | `false` | Reduced spacing |
+| `showAllVariants` | `boolean` | `true` | Show all button variants |
+| `showInputs` | `boolean` | `true` | Show input examples |
+| `class` | `string` | - | Additional CSS classes |
+| `el` | `HTMLDivElement` | - | Bindable element reference |
+| `header` | `Snippet` | - | Custom header content |
+| `sidebar` | `Snippet` | - | Custom sidebar content |
+| `footer` | `Snippet` | - | Custom footer content |
+
+## Component Tokens
+
+Override to customize appearance:
+
+```css
+:root {
+  --stuic-theme-preview-radius: var(--radius-lg);
+  --stuic-theme-preview-gap: 2rem;
+  --stuic-theme-preview-transition: 200ms;
+  --stuic-theme-preview-sidebar-width: 250px;
+}
+```
+
+---
+
+# Theming Best Practices
+
+This component demonstrates the patterns used throughout stuic. Follow these when creating new components.
+
+## 1. Theme Token Reference
+
+### Intent Colors
+
+Communicate **purpose** and **meaning**:
+
+| Token | Purpose |
+|-------|---------|
+| `--stuic-color-primary` | Main actions ("do this") |
+| `--stuic-color-accent` | Highlights ("notice this") |
+| `--stuic-color-destructive` | Dangerous/irreversible actions |
+| `--stuic-color-warning` | Caution states |
+| `--stuic-color-success` | Positive outcomes |
+| `--stuic-color-info` | Neutral information |
+
+Each intent has states and foregrounds:
+- `--stuic-color-{intent}` - base color
+- `--stuic-color-{intent}-hover` - hover state
+- `--stuic-color-{intent}-active` - active/pressed state
+- `--stuic-color-{intent}-foreground` - text on base
+- `--stuic-color-{intent}-foreground-hover`
+- `--stuic-color-{intent}-foreground-active`
+
+### Role Colors
+
+Define **position** in the visual hierarchy:
+
+| Token | Purpose |
+|-------|---------|
+| `--stuic-color-background` | Page background |
+| `--stuic-color-foreground` | Primary text |
+| `--stuic-color-surface` | Card/panel backgrounds |
+| `--stuic-color-surface-foreground` | Text on surfaces |
+| `--stuic-color-muted` | Subtle backgrounds |
+| `--stuic-color-muted-foreground` | Secondary text |
+| `--stuic-color-border` | Border color |
+| `--stuic-color-input` | Input field backgrounds |
+| `--stuic-color-ring` | Focus ring color |
+
+## 2. Internal Variable Pattern
+
+The core theming technique in stuic separates **what colors to use** (intent) from **how to apply them** (variant).
+
+### Step 1: Intent Sets the Palette
+
+```css
+.my-component[data-intent="primary"] {
+  --_color: var(--stuic-color-primary);
+  --_color-hover: var(--stuic-color-primary-hover);
+  --_color-active: var(--stuic-color-primary-active);
+  --_fg: var(--stuic-color-primary-foreground);
+  --_fg-hover: var(--stuic-color-primary-foreground-hover);
+  --_fg-active: var(--stuic-color-primary-foreground-active);
+}
+```
+
+### Step 2: Variant Determines Application
+
+```css
+/* Solid: filled background */
+.my-component[data-variant="solid"] {
+  --_bg: var(--_color);
+  --_text: var(--_fg);
+  --_border: var(--_color);
+}
+
+/* Outline: transparent, colored border */
+.my-component[data-variant="outline"] {
+  --_bg: transparent;
+  --_bg-hover: color-mix(in srgb, var(--_color) 10%, transparent);
+  --_text: var(--_color);
+  --_border: var(--_color);
+}
+```
+
+### Step 3: Base Styles Consume Variables
+
+```css
+.my-component {
+  background: var(--_bg);
+  color: var(--_text);
+  border-color: var(--_border);
+}
+
+.my-component:hover {
+  background: var(--_bg-hover);
+  color: var(--_text-hover);
+  border-color: var(--_border-hover);
+}
+```
+
+This pattern allows any intent + variant combination to work automatically.
+
+## 3. Foreground Pairing Convention
+
+When using a background color, always use its paired foreground for text:
+
+```css
+.card {
+  background: var(--stuic-color-surface);
+  color: var(--stuic-color-surface-foreground);
+}
+
+.muted-section {
+  background: var(--stuic-color-muted);
+  color: var(--stuic-color-muted-foreground);
+}
+```
+
+## 4. Component Tokens
+
+Define component-level tokens in `:root` for easy customization:
+
+```css
+:root {
+  --stuic-my-component-radius: var(--radius-md);
+  --stuic-my-component-padding: 1rem;
+  --stuic-my-component-transition: 150ms;
+}
+
+.my-component {
+  border-radius: var(--stuic-my-component-radius);
+  padding: var(--stuic-my-component-padding);
+  transition: all var(--stuic-my-component-transition);
+}
+```
+
+Users can override globally or locally:
+```css
+/* Global override */
+:root {
+  --stuic-my-component-radius: 0;
+}
+```
+
+```svelte
+<!-- Local override -->
+<MyComponent style="--stuic-my-component-radius: 999px;" />
+```
+
+## 5. State Handling
+
+Always define hover and active states using theme tokens:
+
+```css
+.element {
+  background: var(--stuic-color-surface);
+}
+
+.element:hover {
+  background: var(--stuic-color-surface-hover);
+}
+
+.element:active {
+  background: var(--stuic-color-surface-active);
+}
+
+.element:focus-visible {
+  outline: 3px solid var(--stuic-color-ring);
+  outline-offset: 2px;
+}
+```
+
+## 6. Dark Mode
+
+Themes handle dark mode via `:root.dark` selector. When using theme tokens properly, components don't need explicit dark mode styles - the theme handles everything.
+
+```css
+/* Theme defines both modes */
+:root {
+  --stuic-color-background: var(--color-white);
+  --stuic-color-foreground: var(--color-neutral-900);
+}
+
+:root.dark {
+  --stuic-color-background: var(--color-neutral-950);
+  --stuic-color-foreground: var(--color-neutral-100);
+}
+
+/* Component just uses tokens - works in both modes */
+.my-component {
+  background: var(--stuic-color-background);
+  color: var(--stuic-color-foreground);
+}
+```
+
+## 7. Accessibility
+
+- Use `--stuic-color-ring` for focus indicators
+- Ensure sufficient contrast between background and foreground pairs
+- Respect reduced motion preferences:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .my-component {
+    transition: none;
+  }
+}
+```
+
+## 8. Data Attributes
+
+Use data attributes for styling variants instead of classes:
+
+```svelte
+<button
+  data-intent={intent}
+  data-variant={variant}
+  data-size={size}
+>
+```
+
+```css
+.button[data-intent="primary"] { ... }
+.button[data-variant="outline"] { ... }
+.button[data-size="lg"] { ... }
+```
+
+This keeps the class attribute clean for user customization via `class` prop.