omnidesign 1.0.0

package/recipes/components/bento-grid.md

@@ -0,0 +1,186 @@
+# Bento Grid
+
+A flexible, variable-size card grid layout inspired by bento box design. Supports mixed card dimensions (1×1, 2×1, 1×2, 2×2) with hover lift effects, focus states, and content variations.
+
+## When to Use
+
+**Use bento grids for:**
+- Portfolio or case study showcases
+- Feature highlights with visual variety
+- Product gallery with mixed content types
+- Dashboard layouts with different widget sizes
+- Blog or article collections with featured posts
+
+**Don't use for:**
+- Data tables (use proper table semantics)
+- Uniform card lists (use standard grid)
+- Content requiring strict reading order
+- Mobile-first experiences (complex layouts break on small screens)
+
+## Component Anatomy
+
+```
+┌──────────────────────────────────────────────────────┐
+│  [1×1 Card]  [2×1 Card - Featured]                  │
+│              [Spans 2 columns]                       │
+├──────────────────────────────────────────────────────┤
+│  [1×2 Card]  [1×1 Card]  [1×1 Card]                 │
+│  [Spans 2    [Standard]  [Standard]                 │
+│   rows]                                              │
+├──────────────────────────────────────────────────────┤
+│             [2×2 Card - Hero]                        │
+│             [Spans 2×2 grid]                         │
+└──────────────────────────────────────────────────────┘
+```
+
+## State Matrix
+
+| State | Visual Treatment | Tokens Used |
+|-------|------------------|-------------|
+| **Default** | Card at rest, subtle border, shadow.card applied | `color.surface.raised`, `shadow.card`, `radius.card` |
+| **Hover** | Card lifts 4px (transform: translateY(-4px)), shadow deepens, opacity 100% | `motion.hover`, `shadow.card` (elevated) |
+| **Focus** | Focus ring around card (2px, inset), keyboard navigation visible | `color.focus.ring`, `space.inlineSm` |
+| **Active** | Card background slightly darkened, border color strengthened | `color.surface.sunken`, `color.border.strong` |
+| **Disabled** | Opacity 50%, cursor not-allowed, no hover effect | `color.text.muted`, `motion.hover` (disabled) |
+
+## Token Usage
+
+### Colors
+- **Card Background**: `color.surface.raised` for elevated appearance
+- **Card Border**: `color.border.default` for subtle separation
+- **Text**: `color.text.default` for headings, `color.text.muted` for descriptions
+- **Overlay**: `color.surface.overlay` with 10% opacity for hover darkening
+
+### Spacing
+- **Card Padding**: `space.cardPadding` (6px) internal spacing
+- **Grid Gap**: `space.cardGap` (4px) between cards
+- **Content Stack**: `space.stackMd` (4px) between card title and description
+
+### Typography
+- **Card Title**: `typography.heading.card` (xl, semibold)
+- **Card Description**: `typography.body.default` or `typography.body.small`
+- **Card Meta**: `typography.ui.caption` for dates, tags, or metadata
+
+### Shadows & Radii
+- **Card Radius**: `radius.card` for rounded corners
+- **Card Shadow**: `shadow.card` at rest, elevated shadow on hover
+- **Focus Ring**: 2px inset ring with `color.focus.ring`
+
+## Implementation Notes
+
+### CSS/HTML Approach
+
+**Structure:**
+```
+<div class="bento-grid">
+  <article class="bento-card bento-card--1x1">
+    <img src="..." alt="..." class="bento-card__image">
+    <div class="bento-card__content">
+      <h3 class="bento-card__title">Title</h3>
+      <p class="bento-card__description">Description</p>
+    </div>
+  </article>
+  
+  <article class="bento-card bento-card--2x1">
+    <!-- Featured card content -->
+  </article>
+  
+  <!-- More cards... -->
+</div>
+```
+
+**Key CSS patterns:**
+- Use CSS Grid with `display: grid; grid-template-columns: repeat(4, 1fr)` (4-column base)
+- Apply `grid-column: span 1/2/4` and `grid-row: span 1/2` for sizing variants
+- Use `transition: all 200ms ease-out` for smooth hover effects
+- Apply `transform: translateY(-4px)` on hover for lift effect
+- Use `box-shadow` with `shadow.card` token for depth
+- Implement focus ring with `outline: 2px solid color.focus.ring; outline-offset: 2px`
+
+**Responsive grid:**
+- Desktop (1024px+): 4-column grid with full size variations
+- Tablet (768px): 2-column grid, reduce card sizes (1×1 only, no 2×2)
+- Mobile (375px): 1-column grid, all cards 1×1, stack vertically
+
+**Content variations:**
+- Image-only cards: Full-height image with overlay text
+- Text-only cards: Heading + description + optional CTA
+- Mixed cards: Image + text side-by-side or stacked
+- Interactive cards: Hover reveals additional content or CTA
+
+### React Approach
+
+**Component structure:**
+- Create `<BentoGrid>` wrapper managing grid layout and responsive behavior
+- Create `<BentoCard>` component accepting `size` prop (1x1, 2x1, 1x2, 2x2)
+- Use `children` prop for flexible content (image, text, CTA, etc.)
+- Implement `onHover` state for lift effect and shadow elevation
+- Use CSS Grid with CSS-in-JS or Tailwind for responsive sizing
+
+**State management:**
+- Track hover state per card for visual feedback
+- Use CSS `:hover` and `:focus-visible` for interactive states
+- Implement `useCallback` for hover handlers to prevent unnecessary re-renders
+- Consider `IntersectionObserver` for lazy-loading card images
+
+**Responsive behavior:**
+- Use `useMediaQuery` hook to detect breakpoints
+- Adjust grid columns and card sizes based on viewport
+- Stack cards vertically on mobile, maintain grid on desktop
+
+## Acceptance Criteria
+
+- [ ] Grid uses CSS Grid with proper column/row spanning
+- [ ] Cards support 1×1, 2×1, 1×2, and 2×2 sizes
+- [ ] Hover effect lifts card 4px with shadow elevation
+- [ ] Focus ring visible on keyboard navigation (2px, `color.focus.ring`)
+- [ ] Card padding uses `space.cardPadding` token
+- [ ] Grid gap uses `space.cardGap` token
+- [ ] Responsive: 4-column desktop, 2-column tablet, 1-column mobile
+- [ ] All card titles use `typography.heading.card` token
+- [ ] All descriptions use `typography.body.default` or `typography.body.small`
+- [ ] Card background uses `color.surface.raised` token
+- [ ] Respects `prefers-reduced-motion` (no lift effect)
+- [ ] All text passes color contrast ratio (4.5:1 for body, 3:1 for large text)
+
+## Accessibility
+
+### ARIA & Semantics
+- Use `<article>` for each card (semantic content container)
+- Heading hierarchy: `<h2>` or `<h3>` for card titles (depends on page context)
+- Use `<img>` with descriptive `alt` text for images
+- If card is clickable, use `<a>` or `<button>` with clear link text
+
+### Keyboard Navigation
+- Tab order: Left-to-right, top-to-bottom through cards
+- Focus ring must be visible with 2px width, `color.focus.ring`
+- Ensure focus ring has sufficient contrast against card background
+- Clickable cards must be keyboard accessible (use `<a>` or `<button>`)
+
+### Screen Readers
+- Card titles must be descriptive and unique
+- Image `alt` text must describe content, not just "image"
+- If card contains multiple interactive elements, use `aria-label` for context
+- Use `aria-current="page"` for active/selected cards
+
+### Color & Contrast
+- Text must meet WCAG AA (4.5:1 for body, 3:1 for large text)
+- Don't rely on color alone to indicate card state
+- Ensure sufficient contrast between card background and text
+- Test with WebAIM Contrast Checker
+
+### Motion
+- Respect `prefers-reduced-motion: reduce` by disabling lift effect
+- Hover animations should not auto-play
+- Avoid rapid or flashing animations
+
+### Touch Targets
+- Cards must be minimum 48px × 48px for touch targets
+- Maintain `space.cardGap` (4px) between cards for touch accuracy
+- Ensure clickable areas are easily tappable on mobile
+
+### Content Considerations
+- Avoid relying on image alone to convey meaning
+- Provide text alternative for image-heavy cards
+- Ensure card order makes sense without visual layout
+- Test with screen readers (NVDA, JAWS, VoiceOver)

package/recipes/components/code-block.md

@@ -0,0 +1,503 @@
+# AI Code Block
+
+Syntax-highlighted code display with copy, run, and diff capabilities for AI-generated code.
+
+## When to Use
+- Displaying AI-generated code
+- Code explanations with syntax highlighting
+- Before/after code comparisons
+- Interactive code playgrounds
+- Terminal/command output
+
+## Anatomy
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  CodeBlock                                                  │
+│  ├─ BlockHeader (language, filename, actions)              │
+│  │   ├─ LanguageBadge                                      │
+│  │   ├─ Filename                                           │
+│  │   └─ ActionButtons (copy, run, download)                │
+│  ├─ BlockContent (syntax highlighted code)                 │
+│  │   ├─ LineNumbers (optional)                             │
+│  │   └─ CodeContent (highlighted)                          │
+│  └─ BlockFooter (execution result, apply button)           │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Token Usage
+
+```css
+/* Code Block Container */
+.code-block {
+  background: var(--color-surface-sunken);
+  border: 1px solid var(--color-border-default);
+  border-radius: var(--radius-lg);
+  overflow: hidden;
+  font-family: var(--font-mono);
+  font-size: var(--font-size-sm);
+  line-height: var(--line-height-snug);
+}
+
+/* Block Header */
+.code-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: var(--spacing-sm) var(--spacing-md);
+  background: rgba(0, 0, 0, 0.2);
+  border-bottom: 1px solid var(--color-border-default);
+}
+
+.language-badge {
+  display: inline-flex;
+  align-items: center;
+  padding: var(--spacing-2xs) var(--spacing-xs);
+  background: rgba(37, 99, 235, 0.15);
+  color: var(--color-interactive-primary);
+  border-radius: var(--radius-sm);
+  font-size: var(--font-size-xs);
+  font-weight: var(--font-weight-medium);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+.filename {
+  font-family: var(--font-mono);
+  font-size: var(--font-size-xs);
+  color: var(--color-text-muted);
+  margin-left: var(--spacing-sm);
+}
+
+/* Action Buttons */
+.code-actions {
+  display: flex;
+  gap: var(--spacing-xs);
+}
+
+.code-action-btn {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-2xs);
+  padding: var(--spacing-2xs) var(--spacing-xs);
+  background: transparent;
+  border: 1px solid var(--color-border-default);
+  border-radius: var(--radius-md);
+  color: var(--color-text-muted);
+  font-size: var(--font-size-xs);
+  cursor: pointer;
+  transition: all var(--duration-fast);
+}
+
+.code-action-btn:hover {
+  background: var(--color-surface-raised);
+  border-color: var(--color-border-strong);
+  color: var(--color-text-default);
+}
+
+.code-action-btn.success {
+  background: rgba(34, 197, 94, 0.15);
+  border-color: rgba(34, 197, 94, 0.3);
+  color: #22C55E;
+}
+
+/* Code Content */
+.code-content {
+  padding: var(--spacing-md);
+  overflow-x: auto;
+  background: var(--color-surface-sunken);
+}
+
+/* Line Numbers */
+.code-with-lines {
+  display: flex;
+  gap: var(--spacing-md);
+}
+
+.line-numbers {
+  display: flex;
+  flex-direction: column;
+  color: var(--color-text-muted);
+  font-size: var(--font-size-xs);
+  text-align: right;
+  user-select: none;
+  border-right: 1px solid var(--color-border-default);
+  padding-right: var(--spacing-sm);
+}
+
+.line-number {
+  line-height: 1.8;
+}
+
+/* Syntax Highlighting (Shiki/Prism compatible) */
+.code-content pre {
+  margin: 0;
+  background: transparent !important;
+}
+
+.code-content code {
+  font-family: var(--font-mono);
+  font-size: inherit;
+  background: transparent;
+  padding: 0;
+}
+
+/* Diff View */
+.code-diff {
+  display: flex;
+  flex-direction: column;
+}
+
+.diff-line {
+  display: flex;
+  padding: 0 var(--spacing-md);
+  line-height: 1.8;
+}
+
+.diff-line.added {
+  background: rgba(34, 197, 94, 0.1);
+}
+
+.diff-line.added::before {
+  content: '+';
+  color: #22C55E;
+  margin-right: var(--spacing-sm);
+  font-weight: var(--font-weight-bold);
+}
+
+.diff-line.removed {
+  background: rgba(239, 68, 68, 0.1);
+}
+
+.diff-line.removed::before {
+  content: '-';
+  color: var(--color-status-error);
+  margin-right: var(--spacing-sm);
+  font-weight: var(--font-weight-bold);
+}
+
+.diff-line.unchanged {
+  color: var(--color-text-muted);
+}
+
+.diff-line.unchanged::before {
+  content: ' ';
+  margin-right: var(--spacing-sm);
+}
+
+/* Apply Changes Button */
+.code-footer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: var(--spacing-sm) var(--spacing-md);
+  background: var(--color-surface-raised);
+  border-top: 1px solid var(--color-border-default);
+}
+
+.apply-btn {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-xs);
+  padding: var(--spacing-xs) var(--spacing-md);
+  background: var(--color-interactive-primary);
+  color: var(--color-text-inverted);
+  border: none;
+  border-radius: var(--radius-md);
+  font-size: var(--font-size-sm);
+  font-weight: var(--font-weight-medium);
+  cursor: pointer;
+  transition: all var(--duration-fast);
+}
+
+.apply-btn:hover {
+  background: var(--color-interactive-primary-hover);
+}
+
+/* Terminal Style */
+.terminal-block {
+  background: #0D1117;
+  border-radius: var(--radius-lg);
+  font-family: var(--font-mono);
+  font-size: var(--font-size-sm);
+}
+
+.terminal-header {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-sm);
+  padding: var(--spacing-sm) var(--spacing-md);
+  background: rgba(255, 255, 255, 0.05);
+  border-bottom: 1px solid rgba(255, 255, 255, 0.1);
+}
+
+.terminal-buttons {
+  display: flex;
+  gap: 6px;
+}
+
+.terminal-btn {
+  width: 12px;
+  height: 12px;
+  border-radius: var(--radius-full);
+}
+
+.terminal-btn.red { background: #FF5F56; }
+.terminal-btn.yellow { background: #FFBD2E; }
+.terminal-btn.green { background: #27C93F; }
+
+.terminal-content {
+  padding: var(--spacing-md);
+  color: #E6EDF3;
+  line-height: 1.6;
+}
+
+.terminal-prompt {
+  color: #7EE787;
+}
+
+.terminal-command {
+  color: #E6EDF3;
+}
+
+.terminal-output {
+  color: #8B949E;
+}
+```
+
+## State Matrix
+
+| Element | Default | Hover | Copied | Running |
+|---------|---------|-------|--------|---------|
+| Copy Button | ghost | raised | success green | - |
+| Run Button | ghost | raised | - | spinner |
+| Apply Button | primary | primary-hover | - | loading |
+| Code Block | sunken bg | - | - | - |
+| Diff Line | context-based | - | - | - |
+
+## Accessibility
+
+```html
+<figure class="code-block" role="region" aria-label="Code example: example.tsx">
+  <figcaption class="code-header">
+    <div class="file-info">
+      <span class="language-badge">TSX</span>
+      <span class="filename">example.tsx</span>
+    </div>
+    
+    <div class="code-actions">
+      <button 
+        class="code-action-btn" 
+        aria-label="Copy code to clipboard"
+        onClick={handleCopy}
+      >
+        <CopyIcon aria-hidden="true" />
+        <span>Copy</span>
+      </button>
+      
+      <button 
+        class="code-action-btn" 
+        aria-label="Download file"
+        onClick={handleDownload}
+      >
+        <DownloadIcon aria-hidden="true" />
+        <span>Download</span>
+      </button>
+    </div>
+  </figcaption>
+  
+  <div class="code-with-lines">
+    <div class="line-numbers" aria-hidden="true">
+      <span class="line-number">1</span>
+      <span class="line-number">2</span>
+      <span class="line-number">3</span>
+    </div>
+    
+    <pre class="code-content">
+      <code>const example = "Hello World";</code>
+    </pre>
+  </div>
+</figure>
+
+<!-- Screen reader announcement -->
+<div aria-live="polite" aria-atomic="true" class="sr-only">
+  Code copied to clipboard
+</div>
+```
+
+## Example: Basic Code Block
+
+```tsx
+function CodeBlock({ code, language, filename, onCopy }) {
+  const [copied, setCopied] = useState(false);
+  
+  const handleCopy = async () => {
+    await navigator.clipboard.writeText(code);
+    setCopied(true);
+    setTimeout(() => setCopied(false), 2000);
+    onCopy?.();
+  };
+  
+  return (
+    <figure className="code-block">
+      <figcaption className="code-header">
+        <div className="file-info">
+          <span className="language-badge">{language}</span>
+          {filename && <span className="filename">{filename}</span>}
+        </div>
+        
+        <div className="code-actions">
+          <button 
+            className={`code-action-btn ${copied ? 'success' : ''}`}
+            onClick={handleCopy}
+            aria-label={copied ? 'Copied' : 'Copy code'}
+          >
+            {copied ? <CheckIcon /> : <CopyIcon />}
+            <span>{copied ? 'Copied!' : 'Copy'}</span>
+          </button>
+        </div>
+      </figcaption>
+      
+      <div className="code-content">
+        <pre>
+          <code dangerouslySetInnerHTML={{ __html: highlightedCode }} />
+        </pre>
+      </div>
+    </figure>
+  );
+}
+```
+
+## Example: Code Diff View
+
+```tsx
+function CodeDiff({ original, modified, filename }) {
+  const diff = computeDiff(original, modified);
+  
+  return (
+    <figure className="code-block diff-view">
+      <figcaption className="code-header">
+        <span className="filename">{filename}</span>
+        <span className="diff-stats">
+          <span className="added">+{diff.additions}</span>
+          <span className="removed">-{diff.deletions}</span>
+        </span>
+      </figcaption>
+      
+      <div className="code-diff">
+        {diff.lines.map((line, i) => (
+          <div 
+            key={i} 
+            className={`diff-line ${line.type}`}
+            aria-label={line.type === 'added' ? 'Added line' : line.type === 'removed' ? 'Removed line' : 'Unchanged line'}
+          >
+            <span className="diff-content">{line.content}</span>
+          </div>
+        ))}
+      </div>
+      
+      <footer className="code-footer">
+        <span className="diff-summary">
+          {diff.additions} additions, {diff.deletions} deletions
+        </span>
+        <button className="apply-btn">
+          <CheckIcon />
+          Apply Changes
+        </button>
+      </footer>
+    </figure>
+  );
+}
+```
+
+## Example: Terminal Output
+
+```tsx
+function TerminalBlock({ command, output, workingDir = '~' }) {
+  return (
+    <div className="terminal-block" role="region" aria-label="Terminal output">
+      <div className="terminal-header">
+        <div className="terminal-buttons" aria-hidden="true">
+          <span className="terminal-btn red"></span>
+          <span className="terminal-btn yellow"></span>
+          <span className="terminal-btn green"></span>
+        </div>
+        <span className="terminal-title">Terminal</span>
+      </div>
+      
+      <div className="terminal-content">
+        <div className="terminal-line">
+          <span className="terminal-prompt">➜ {workingDir}</span>
+          <span className="terminal-command"> {command}</span>
+        </div>
+        
+        <div className="terminal-output">
+          {output.split('\n').map((line, i) => (
+            <div key={i}>{line}</div>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+## Example: Runnable Code Block
+
+```tsx
+function RunnableCodeBlock({ code, language, onRun }) {
+  const [isRunning, setIsRunning] = useState(false);
+  const [result, setResult] = useState(null);
+  
+  const handleRun = async () => {
+    setIsRunning(true);
+    try {
+      const output = await onRun(code);
+      setResult({ success: true, output });
+    } catch (error) {
+      setResult({ success: false, error: error.message });
+    } finally {
+      setIsRunning(false);
+    }
+  };
+  
+  return (
+    <figure className="code-block runnable">
+      <figcaption className="code-header">
+        <span className="language-badge">{language}</span>
+        
+        <button 
+          className="code-action-btn run-btn"
+          onClick={handleRun}
+          disabled={isRunning}
+        >
+          {isRunning ? <Spinner /> : <PlayIcon />}
+          <span>{isRunning ? 'Running...' : 'Run'}</span>
+        </button>
+      </figcaption>
+      
+      <div className="code-content">
+        <pre><code>{code}</code></pre>
+      </div>
+      
+      {result && (
+        <footer className="code-footer execution-result">
+          {result.success ? (
+            <div className="success-output">{result.output}</div>
+          ) : (
+            <div className="error-output">{result.error}</div>
+          )}
+        </footer>
+      )}
+    </figure>
+  );
+}
+```
+
+## Tokens Used
+
+- **color**: surface-sunken, surface-raised, interactive-primary, interactive-primary-hover, text-default, text-inverted, text-muted, border-default, border-strong, status-success, status-error
+- **spacing**: 2xs, xs, sm, md
+- **radii**: sm, md, lg
+- **typography**: font-mono, size-xs, size-sm, weight-medium
+- **motion**: duration-fast