@jack200714/mafw 4.5.1

package/.opencode/skills/design-system/references/semantic-tokens.md

@@ -0,0 +1,215 @@
+# Semantic Tokens
+
+Purpose-based aliases referencing primitive tokens.
+
+## Color Semantics
+
+### Background & Foreground
+
+```css
+:root {
+  /* Page background */
+  --color-background: var(--color-gray-50);
+  --color-foreground: var(--color-gray-900);
+
+  /* Card/surface background */
+  --color-card: white;
+  --color-card-foreground: var(--color-gray-900);
+
+  /* Popover/dropdown */
+  --color-popover: white;
+  --color-popover-foreground: var(--color-gray-900);
+}
+```
+
+### Primary
+
+```css
+:root {
+  --color-primary: var(--color-blue-600);
+  --color-primary-hover: var(--color-blue-700);
+  --color-primary-active: var(--color-blue-800);
+  --color-primary-foreground: white;
+}
+```
+
+### Secondary
+
+```css
+:root {
+  --color-secondary: var(--color-gray-100);
+  --color-secondary-hover: var(--color-gray-200);
+  --color-secondary-foreground: var(--color-gray-900);
+}
+```
+
+### Muted
+
+```css
+:root {
+  --color-muted: var(--color-gray-100);
+  --color-muted-foreground: var(--color-gray-500);
+}
+```
+
+### Accent
+
+```css
+:root {
+  --color-accent: var(--color-gray-100);
+  --color-accent-foreground: var(--color-gray-900);
+}
+```
+
+### Destructive
+
+```css
+:root {
+  --color-destructive: var(--color-red-600);
+  --color-destructive-hover: var(--color-red-700);
+  --color-destructive-foreground: white;
+}
+```
+
+### Status Colors
+
+```css
+:root {
+  --color-success: var(--color-green-600);
+  --color-success-foreground: white;
+
+  --color-warning: var(--color-yellow-500);
+  --color-warning-foreground: var(--color-gray-900);
+
+  --color-error: var(--color-red-600);
+  --color-error-foreground: white;
+
+  --color-info: var(--color-blue-500);
+  --color-info-foreground: white;
+}
+```
+
+### Border & Ring
+
+```css
+:root {
+  --color-border: var(--color-gray-200);
+  --color-input: var(--color-gray-200);
+  --color-ring: var(--color-blue-500);
+}
+```
+
+## Spacing Semantics
+
+```css
+:root {
+  /* Component internal spacing */
+  --spacing-component-xs: var(--space-1);
+  --spacing-component-sm: var(--space-2);
+  --spacing-component: var(--space-3);
+  --spacing-component-lg: var(--space-4);
+
+  /* Section spacing */
+  --spacing-section-sm: var(--space-8);
+  --spacing-section: var(--space-12);
+  --spacing-section-lg: var(--space-16);
+
+  /* Page margins */
+  --spacing-page-x: var(--space-4);
+  --spacing-page-y: var(--space-6);
+}
+```
+
+## Typography Semantics
+
+```css
+:root {
+  /* Headings */
+  --font-heading: var(--font-size-2xl);
+  --font-heading-lg: var(--font-size-3xl);
+  --font-heading-xl: var(--font-size-4xl);
+
+  /* Body */
+  --font-body: var(--font-size-base);
+  --font-body-sm: var(--font-size-sm);
+  --font-body-lg: var(--font-size-lg);
+
+  /* Labels & Captions */
+  --font-label: var(--font-size-sm);
+  --font-caption: var(--font-size-xs);
+}
+```
+
+## Interactive States
+
+```css
+:root {
+  /* Focus ring */
+  --ring-width: 2px;
+  --ring-offset: 2px;
+  --ring-color: var(--color-ring);
+
+  /* Opacity for disabled */
+  --opacity-disabled: 0.5;
+
+  /* Transitions */
+  --transition-colors: color, background-color, border-color;
+  --transition-transform: transform;
+  --transition-all: all;
+}
+```
+
+## Dark Mode Overrides
+
+```css
+.dark {
+  --color-background: var(--color-gray-950);
+  --color-foreground: var(--color-gray-50);
+
+  --color-card: var(--color-gray-900);
+  --color-card-foreground: var(--color-gray-50);
+
+  --color-popover: var(--color-gray-900);
+  --color-popover-foreground: var(--color-gray-50);
+
+  --color-muted: var(--color-gray-800);
+  --color-muted-foreground: var(--color-gray-400);
+
+  --color-secondary: var(--color-gray-800);
+  --color-secondary-foreground: var(--color-gray-50);
+
+  --color-accent: var(--color-gray-800);
+  --color-accent-foreground: var(--color-gray-50);
+
+  --color-border: var(--color-gray-800);
+  --color-input: var(--color-gray-800);
+}
+```
+
+## Usage Patterns
+
+### Applying Semantic Tokens
+
+```css
+/* Good - uses semantic tokens */
+.card {
+  background: var(--color-card);
+  color: var(--color-card-foreground);
+  border: 1px solid var(--color-border);
+}
+
+/* Bad - uses primitive tokens directly */
+.card {
+  background: var(--color-gray-50);
+  color: var(--color-gray-900);
+}
+```
+
+### Theme Switching
+
+Semantic tokens enable instant theme switching:
+
+```js
+// Toggle dark mode
+document.documentElement.classList.toggle('dark');
+```

package/.opencode/skills/design-system/references/states-and-variants.md

@@ -0,0 +1,241 @@
+# States and Variants
+
+Component state definitions and variant patterns.
+
+## Interactive States
+
+### State Definitions
+
+| State | Trigger | Visual Change |
+|-------|---------|---------------|
+| default | None | Base appearance |
+| hover | Mouse over | Slight color shift |
+| focus | Tab/click | Focus ring |
+| active | Mouse down | Darkest color |
+| disabled | disabled attr | Reduced opacity |
+| loading | Async action | Spinner + opacity |
+
+### State Priority
+
+When multiple states apply, priority (highest to lowest):
+
+1. disabled
+2. loading
+3. active
+4. focus
+5. hover
+6. default
+
+### State Transitions
+
+```css
+/* Standard transition for interactive elements */
+.interactive {
+  transition-property: color, background-color, border-color, box-shadow;
+  transition-duration: var(--duration-fast);
+  transition-timing-function: ease-in-out;
+}
+```
+
+| Transition | Duration | Easing |
+|------------|----------|--------|
+| Color changes | 150ms | ease-in-out |
+| Background | 150ms | ease-in-out |
+| Transform | 200ms | ease-out |
+| Opacity | 150ms | ease |
+| Shadow | 200ms | ease-out |
+
+## Focus States
+
+### Focus Ring Spec
+
+```css
+/* Standard focus ring */
+.focusable:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 var(--ring-offset) var(--color-background),
+              0 0 0 calc(var(--ring-offset) + var(--ring-width)) var(--ring-color);
+}
+```
+
+| Property | Value |
+|----------|-------|
+| Ring width | 2px |
+| Ring offset | 2px |
+| Ring color | primary (blue-500) |
+| Offset color | background |
+
+### Focus Within
+
+```css
+/* Container focus when child is focused */
+.container:focus-within {
+  border-color: var(--color-ring);
+}
+```
+
+## Disabled States
+
+### Visual Treatment
+
+```css
+.disabled {
+  opacity: var(--opacity-disabled); /* 0.5 */
+  pointer-events: none;
+  cursor: not-allowed;
+}
+```
+
+| Property | Disabled Value |
+|----------|----------------|
+| Opacity | 50% |
+| Pointer events | none |
+| Cursor | not-allowed |
+| Background | muted |
+| Color | muted-foreground |
+
+### Accessibility
+
+- Use `aria-disabled="true"` for semantic disabled
+- Use `disabled` attribute for form elements
+- Maintain sufficient contrast (3:1 minimum)
+
+## Loading States
+
+### Spinner Placement
+
+| Component | Spinner Position |
+|-----------|------------------|
+| Button | Replace icon or center |
+| Input | Trailing position |
+| Card | Center overlay |
+| Page | Center of viewport |
+
+### Loading Treatment
+
+```css
+.loading {
+  position: relative;
+  pointer-events: none;
+}
+
+.loading::after {
+  content: '';
+  /* spinner styles */
+}
+
+.loading > * {
+  opacity: 0.7;
+}
+```
+
+## Error States
+
+### Visual Indicators
+
+```css
+.error {
+  border-color: var(--color-error);
+  color: var(--color-error);
+}
+
+.error:focus-visible {
+  box-shadow: 0 0 0 2px var(--color-background),
+              0 0 0 4px var(--color-error);
+}
+```
+
+| Element | Error Treatment |
+|---------|-----------------|
+| Input border | red-500 |
+| Input focus ring | red/20% |
+| Helper text | red-600 |
+| Icon | red-500 |
+
+### Error Messages
+
+- Position below input
+- Use error color
+- Include icon for accessibility
+- Clear on valid input
+
+## Variant Patterns
+
+### Color Variants
+
+```css
+/* Pattern for color variants */
+.component {
+  --component-bg: var(--color-primary);
+  --component-fg: var(--color-primary-foreground);
+  background: var(--component-bg);
+  color: var(--component-fg);
+}
+
+.component.secondary {
+  --component-bg: var(--color-secondary);
+  --component-fg: var(--color-secondary-foreground);
+}
+
+.component.destructive {
+  --component-bg: var(--color-destructive);
+  --component-fg: var(--color-destructive-foreground);
+}
+```
+
+### Size Variants
+
+```css
+/* Pattern for size variants */
+.component {
+  --component-height: 40px;
+  --component-padding: var(--space-4);
+  --component-font: var(--font-size-sm);
+}
+
+.component.sm {
+  --component-height: 32px;
+  --component-padding: var(--space-3);
+  --component-font: var(--font-size-xs);
+}
+
+.component.lg {
+  --component-height: 48px;
+  --component-padding: var(--space-6);
+  --component-font: var(--font-size-base);
+}
+```
+
+## Accessibility Requirements
+
+### Color Contrast
+
+| Element | Minimum Ratio |
+|---------|---------------|
+| Normal text | 4.5:1 |
+| Large text (18px+) | 3:1 |
+| UI components | 3:1 |
+| Focus indicator | 3:1 |
+
+### State Indicators
+
+- Never rely on color alone
+- Use icons, text, or patterns
+- Ensure focus is visible
+- Provide loading announcements
+
+### ARIA States
+
+```html
+<!-- Disabled -->
+<button disabled aria-disabled="true">Submit</button>
+
+<!-- Loading -->
+<button aria-busy="true" aria-describedby="loading-text">
+  <span id="loading-text" class="sr-only">Loading...</span>
+</button>
+
+<!-- Error -->
+<input aria-invalid="true" aria-describedby="error-msg">
+<span id="error-msg" role="alert">Error message</span>
+```

package/.opencode/skills/design-system/references/tailwind-integration.md

@@ -0,0 +1,251 @@
+# Tailwind Integration
+
+Map design system tokens to Tailwind CSS configuration.
+
+## CSS Variables Setup
+
+### Base Layer
+
+```css
+/* globals.css */
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  :root {
+    /* Primitives */
+    --color-blue-600: 37 99 235;  /* HSL: 217 91% 60% */
+
+    /* Semantic */
+    --background: 0 0% 100%;
+    --foreground: 222 47% 11%;
+    --primary: 217 91% 60%;
+    --primary-foreground: 0 0% 100%;
+    --secondary: 220 14% 96%;
+    --secondary-foreground: 222 47% 11%;
+    --muted: 220 14% 96%;
+    --muted-foreground: 220 9% 46%;
+    --accent: 220 14% 96%;
+    --accent-foreground: 222 47% 11%;
+    --destructive: 0 84% 60%;
+    --destructive-foreground: 0 0% 100%;
+    --border: 220 13% 91%;
+    --input: 220 13% 91%;
+    --ring: 217 91% 60%;
+    --radius: 0.5rem;
+  }
+
+  .dark {
+    --background: 222 47% 4%;
+    --foreground: 210 40% 98%;
+    --primary: 217 91% 60%;
+    --primary-foreground: 0 0% 100%;
+    --secondary: 217 33% 17%;
+    --secondary-foreground: 210 40% 98%;
+    --muted: 217 33% 17%;
+    --muted-foreground: 215 20% 65%;
+    --accent: 217 33% 17%;
+    --accent-foreground: 210 40% 98%;
+    --destructive: 0 62% 30%;
+    --destructive-foreground: 0 0% 100%;
+    --border: 217 33% 17%;
+    --input: 217 33% 17%;
+    --ring: 217 91% 60%;
+  }
+}
+```
+
+## Tailwind Config
+
+### tailwind.config.ts
+
+```typescript
+import type { Config } from 'tailwindcss'
+
+const config: Config = {
+  darkMode: ['class'],
+  content: ['./src/**/*.{ts,tsx}'],
+  theme: {
+    extend: {
+      colors: {
+        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))',
+        },
+        muted: {
+          DEFAULT: 'hsl(var(--muted))',
+          foreground: 'hsl(var(--muted-foreground))',
+        },
+        accent: {
+          DEFAULT: 'hsl(var(--accent))',
+          foreground: 'hsl(var(--accent-foreground))',
+        },
+        destructive: {
+          DEFAULT: 'hsl(var(--destructive))',
+          foreground: 'hsl(var(--destructive-foreground))',
+        },
+        border: 'hsl(var(--border))',
+        input: 'hsl(var(--input))',
+        ring: 'hsl(var(--ring))',
+        card: {
+          DEFAULT: 'hsl(var(--card))',
+          foreground: 'hsl(var(--card-foreground))',
+        },
+      },
+      borderRadius: {
+        lg: 'var(--radius)',
+        md: 'calc(var(--radius) - 2px)',
+        sm: 'calc(var(--radius) - 4px)',
+      },
+    },
+  },
+  plugins: [],
+}
+
+export default config
+```
+
+## HSL Format Benefits
+
+Using HSL without function allows opacity modifiers:
+
+```tsx
+// With HSL format (space-separated)
+<div className="bg-primary/50">   // 50% opacity
+<div className="text-primary/80"> // 80% opacity
+
+// CSS output
+background-color: hsl(217 91% 60% / 0.5);
+```
+
+## Component Classes
+
+### Button Example
+
+```css
+@layer components {
+  .btn {
+    @apply inline-flex items-center justify-center
+           rounded-md font-medium
+           transition-colors
+           focus-visible:outline-none focus-visible:ring-2
+           focus-visible:ring-ring focus-visible:ring-offset-2
+           disabled:pointer-events-none disabled:opacity-50;
+  }
+
+  .btn-default {
+    @apply bg-primary text-primary-foreground
+           hover:bg-primary/90;
+  }
+
+  .btn-secondary {
+    @apply bg-secondary text-secondary-foreground
+           hover:bg-secondary/80;
+  }
+
+  .btn-outline {
+    @apply border border-input bg-background
+           hover:bg-accent hover:text-accent-foreground;
+  }
+
+  .btn-ghost {
+    @apply hover:bg-accent hover:text-accent-foreground;
+  }
+
+  .btn-destructive {
+    @apply bg-destructive text-destructive-foreground
+           hover:bg-destructive/90;
+  }
+
+  /* Sizes */
+  .btn-sm { @apply h-8 px-3 text-xs; }
+  .btn-md { @apply h-10 px-4 text-sm; }
+  .btn-lg { @apply h-12 px-6 text-base; }
+}
+```
+
+## Spacing Integration
+
+```typescript
+// tailwind.config.ts
+theme: {
+  extend: {
+    spacing: {
+      // Map to CSS variables if needed
+      'section': 'var(--spacing-section)',
+      'component': 'var(--spacing-component)',
+    }
+  }
+}
+```
+
+## Animation Tokens
+
+```typescript
+// tailwind.config.ts
+theme: {
+  extend: {
+    transitionDuration: {
+      fast: '150ms',
+      normal: '200ms',
+      slow: '300ms',
+    },
+    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',
+    },
+  }
+}
+```
+
+## Dark Mode Toggle
+
+```typescript
+// Toggle dark mode
+function toggleDarkMode() {
+  document.documentElement.classList.toggle('dark')
+}
+
+// System preference
+if (window.matchMedia('(prefers-color-scheme: dark)').matches) {
+  document.documentElement.classList.add('dark')
+}
+```
+
+## shadcn/ui Alignment
+
+This configuration aligns with shadcn/ui conventions:
+
+- Same CSS variable naming
+- Same HSL format
+- Same color scale structure
+- Compatible with `npx shadcn@latest add` commands
+
+### Using with shadcn/ui
+
+```bash
+# Initialize (uses same token structure)
+npx shadcn@latest init
+
+# Add components (styled with these tokens)
+npx shadcn@latest add button card input
+```
+
+Components will automatically use your design system tokens.