diff --git a/.opencode/agent/subagents/core/externalscout.md b/.opencode/agent/subagents/core/externalscout.md index 4844ea9..6b53c09 100644 --- a/.opencode/agent/subagents/core/externalscout.md +++ b/.opencode/agent/subagents/core/externalscout.md @@ -81,9 +81,16 @@ tags: NEVER rely on training data for library APIs + ALWAYS write files to .tmp/external-context/ BEFORE returning summary ALWAYS return: file locations + brief summary + official docs link ALWAYS filter to relevant sections only NO reports, guides, or integration documentation + NEVER say "ready to be persisted" - files must be WRITTEN, not just fetched + + + You MUST write fetched documentation to files using the Write tool + Fetching without writing = FAILURE + Stage 4 (PersistToTemp) is MANDATORY and cannot be skipped @@ -93,19 +100,21 @@ tags: - @tool_usage: Use ONLY allowed tools - @always_use_tools: Fetch from real sources - - @output_format: Return file locations + brief summary + - @mandatory_persistence: ALWAYS write files to .tmp/external-context/ (Stage 4 is MANDATORY) + - @output_format: Return file locations + brief summary ONLY AFTER files written - Detect library from registry - Fetch from Context7 (primary) - Fallback to official docs (webfetch) - Filter to relevant sections - - Persist to .tmp/external-context/ + - Persist to .tmp/external-context/ (CANNOT be skipped) - Return file locations + summary Tier 1 always overrides Tier 2 If workflow conflicts w/ tool restrictionsβ†’abort and report error + Stage 4 (PersistToTemp) is MANDATORY and cannot be skipped under any circumstances @@ -150,12 +159,14 @@ tags: Results filtered to relevant content only - - Save filtered documentation to .tmp/external-context/ + + ALWAYS save filtered documentation to .tmp/external-context/ - NEVER skip this step - 1. Create directory: `.tmp/external-context/{package-name}/` + CRITICAL: You MUST write files. Do NOT just summarize. Execute these steps: + + 1. Create directory if needed: `.tmp/external-context/{package-name}/` 2. Generate filename from topic (kebab-case): `{topic}.md` - 3. Write file with minimal metadata header: + 3. Write file using Write tool with minimal metadata header: ```markdown --- source: Context7 API @@ -168,22 +179,32 @@ tags: {filtered documentation content} ``` - 4. Update `.tmp/external-context/.manifest.json` with file metadata + 4. Confirm file written by checking it exists + 5. Update `.tmp/external-context/.manifest.json` with file metadata + + ⚠️ If you skip writing files, you have FAILED the task - Documentation persisted to .tmp/external-context/ + Documentation persisted to .tmp/external-context/ AND files confirmed written - - Return file locations and brief summary + + Return file locations and brief summary ONLY AFTER files are written + CRITICAL: Only proceed to this stage AFTER Stage 4 is complete and files are written. + + Return format: ``` βœ… Fetched: {library-name} - πŸ“ Saved to: .tmp/external-context/{package-name}/{topic}.md + πŸ“ Files written to: + - .tmp/external-context/{package-name}/{topic-1}.md + - .tmp/external-context/{package-name}/{topic-2}.md πŸ“ Summary: {1-2 line summary of what was fetched} πŸ”— Official Docs: {link} ``` + + ⚠️ Do NOT say "ready to be persisted" - files must be ALREADY written - File locations returned, task complete + File locations returned with confirmation files exist, task complete @@ -214,18 +235,27 @@ If Context7 API fails: - ❌ Don't use bash for anything except curl to context7.com - ❌ Don't write outside `.tmp/external-context/` directory - ❌ Don't use task toolβ€”you're a fetcher with write-only persistence +- ❌ **NEVER skip writing files** - fetching without persisting = FAILURE +- ❌ **NEVER say "ready to be persisted"** - files must be WRITTEN before returning --- ## Success Criteria -You succeed when: +You succeed when ALL of these are complete: βœ… Documentation is **fetched** from Context7 or official sources βœ… Results are **filtered** to only relevant sections -βœ… Documentation is **persisted** to `.tmp/external-context/{package-name}/{topic}.md` +βœ… Files are **WRITTEN** to `.tmp/external-context/{package-name}/{topic}.md` using Write tool +βœ… Files are **CONFIRMED** to exist (not just "ready to be persisted") βœ… **File locations returned** with brief summary βœ… **Official docs link** provided +❌ You FAIL if you: +- Fetch docs but don't write files +- Say "ready to be persisted" without actually writing +- Skip Stage 4 (PersistToTemp) +- Return summary without file locations + --- ## References diff --git a/.opencode/context/core/visual-development.md b/.opencode/context/core/visual-development.md index b25cf10..d2337e4 100644 --- a/.opencode/context/core/visual-development.md +++ b/.opencode/context/core/visual-development.md @@ -13,9 +13,9 @@ | **Edit existing image** | This file | Image Specialist | tool:gemini | | **UI mockup (static)** | This file | Image Specialist | tool:gemini | | **Interactive UI design** | `workflows/design-iteration.md` | - | - | -| **Design system** | `development/design-systems.md` | - | - | -| **UI standards** | `development/ui-styling-standards.md` | - | - | -| **Animation patterns** | `development/animation-patterns.md` | - | - | +| **Design system** | `ui/web/design-systems.md` | - | - | +| **UI standards** | `ui/web/ui-styling-standards.md` | - | - | +| **Animation patterns** | `ui/web/animation-patterns.md` | - | - | --- @@ -448,9 +448,9 @@ After receiving output: ## Related Context - **UI Design Workflow**: `.opencode/context/core/workflows/design-iteration.md` -- **Design Systems**: `.opencode/context/development/design-systems.md` -- **UI Styling Standards**: `.opencode/context/development/ui-styling-standards.md` -- **Animation Patterns**: `.opencode/context/development/animation-patterns.md` +- **Design Systems**: `.opencode/context/ui/web/design-systems.md` +- **UI Styling Standards**: `.opencode/context/ui/web/ui-styling-standards.md` +- **Animation Patterns**: `.opencode/context/ui/web/animation-patterns.md` - **Subagent Invocation Guide**: `.opencode/context/openagents-repo/guides/subagent-invocation.md` - **Agent Capabilities**: `.opencode/context/openagents-repo/core-concepts/agents.md` diff --git a/.opencode/context/core/workflows/design-iteration.md b/.opencode/context/core/workflows/design-iteration.md index c7b2e2b..d0383d6 100644 --- a/.opencode/context/core/workflows/design-iteration.md +++ b/.opencode/context/core/workflows/design-iteration.md @@ -652,9 +652,9 @@ Before presenting each stage: ## References -- [Design Systems Context](../development/design-systems.md) -- [UI Styling Standards](../development/ui-styling-standards.md) -- [Animation Patterns](../development/animation-patterns.md) -- [Design Assets](../development/design-assets.md) +- [Design Systems Context](../ui/web/design-systems.md) +- [UI Styling Standards](../ui/web/ui-styling-standards.md) +- [Animation Patterns](../ui/web/animation-patterns.md) +- [Design Assets](../ui/web/design-assets.md) - [ASCII Art Generator](https://www.asciiart.eu/) - [WCAG Contrast Checker](https://webaim.org/resources/contrastchecker/) diff --git a/.opencode/context/development/README.md b/.opencode/context/development/README.md deleted file mode 100644 index 5e8f678..0000000 --- a/.opencode/context/development/README.md +++ /dev/null @@ -1,46 +0,0 @@ -# Development Context - -This directory contains context files for software development best practices, patterns, and guidelines. - -## Available Context Files - -### clean-code.md -Core coding standards and best practices for writing clean, maintainable code across all languages. - -**Topics covered**: -- Meaningful naming conventions -- Function design principles -- Error handling patterns -- Language-specific guidelines (JavaScript, Python, Go, Rust) - -**Used by**: frontend-specialist, devops-specialist, opencoder - -### react-patterns.md -Modern React patterns, hooks usage, and component design principles. - -**Topics covered**: -- Functional components and hooks -- Custom hooks for reusable logic -- State management patterns -- Performance optimization -- Code splitting and lazy loading - -**Used by**: frontend-specialist - -### api-design.md -REST API design principles, GraphQL patterns, and API versioning strategies. - -**Topics covered**: -- RESTful resource design -- HTTP methods and status codes -- GraphQL schema design -- API versioning strategies -- Authentication and authorization - -**Used by**: opencoder - -## Usage - -These context files are referenced by development-focused agents to ensure consistent coding standards and best practices across the project. - -Agents load these files before implementing code to align with established patterns and conventions. diff --git a/.opencode/context/development/ai/mastra-ai/README.md b/.opencode/context/development/ai/mastra-ai/README.md deleted file mode 100644 index d98f7a4..0000000 --- a/.opencode/context/development/ai/mastra-ai/README.md +++ /dev/null @@ -1,43 +0,0 @@ -# Mastra Context - -**Purpose**: Documentation and quick references for Mastra implementation in this project. - -**Last Updated**: 2026-01-09 - ---- - -## Navigation - -### Concepts -| File | Description | Priority | -|------|-------------|----------| -| [core.md](concepts/core.md) | Central orchestration layer | critical | -| [workflows.md](concepts/workflows.md) | Linear and parallel execution chains | critical | -| [agents-tools.md](concepts/agents-tools.md) | Reusable units of logic and LLM entities | high | -| [evaluations.md](concepts/evaluations.md) | Quality assurance and scoring | high | -| [storage.md](concepts/storage.md) | Persistence layer and schema | high | - -### Guides -| File | Description | Priority | -|------|-------------|----------| -| [testing.md](guides/testing.md) | How to run and validate components | high | -| [modular-building.md](guides/modular-building.md) | Best practices for large-scale Mastra | high | -| [workflow-step-structure.md](guides/workflow-step-structure.md) | Maintainable step patterns | critical | - -### Lookup -| File | Description | Priority | -|------|-------------|----------| -| [mastra-config.md](lookup/mastra-config.md) | File locations and database tables | high | - -### Errors -| File | Description | Priority | -|------|-------------|----------| -| [mastra-errors.md](errors/mastra-errors.md) | Common errors and recovery | high | - - ---- - -## Quick Start -1. **Explore Config**: See `src/mastra/index.ts` for the main Mastra instance. -2. **Check Workflows**: Look at `src/mastra/workflows/` for business logic. -3. **View Traces**: Run `npm run traces` to see execution history. diff --git a/.opencode/context/development/animation-patterns.md b/.opencode/context/development/animation-patterns.md deleted file mode 100644 index 0e4fd14..0000000 --- a/.opencode/context/development/animation-patterns.md +++ /dev/null @@ -1,753 +0,0 @@ - -# Animation Patterns - -## Overview - -Standards and patterns for UI animations, micro-interactions, and transitions. Animations should feel natural, purposeful, and enhance user experience without causing distraction. - -## Quick Reference - -**Timing**: 150-400ms for most interactions -**Easing**: ease-out for entrances, ease-in for exits -**Purpose**: Every animation should have a clear purpose -**Performance**: Use transform and opacity for 60fps - ---- - -## Animation Micro-Syntax - -### Notation Guide - -**Format**: `element: duration easing [properties] modifiers` - -**Symbols**: -- `β†’` = transition from β†’ to -- `Β±` = oscillate/shake -- `β†—` = increase -- `β†˜` = decrease -- `∞` = infinite loop -- `Γ—N` = repeat N times -- `+Nms` = delay N milliseconds - -**Properties**: -- `Y` = translateY -- `X` = translateX -- `S` = scale -- `R` = rotate -- `Ξ±` = opacity -- `bg` = background - -**Example**: `button: 200ms ease-out [S1β†’1.05, Ξ±0.8β†’1]` -- Button scales from 1 to 1.05 and fades from 0.8 to 1 over 200ms with ease-out - ---- - -## Core Animation Principles - -### Timing Standards - -``` -Ultra-fast: 100-150ms (micro-feedback, hover states) -Fast: 150-250ms (button clicks, toggles) -Standard: 250-350ms (modals, dropdowns, navigation) -Moderate: 350-500ms (page transitions, complex animations) -Slow: 500-800ms (dramatic reveals, storytelling) -``` - -### Easing Functions - -```css -/* Entrances - start slow, end fast */ -ease-out: cubic-bezier(0, 0, 0.2, 1); - -/* Exits - start fast, end slow */ -ease-in: cubic-bezier(0.4, 0, 1, 1); - -/* Both - smooth throughout */ -ease-in-out: cubic-bezier(0.4, 0, 0.2, 1); - -/* Bounce - playful, attention-grabbing */ -bounce: cubic-bezier(0.68, -0.55, 0.265, 1.55); - -/* Elastic - spring-like */ -elastic: cubic-bezier(0.68, -0.6, 0.32, 1.6); -``` - -### Performance Guidelines - -**60fps Animations** (GPU-accelerated): -- βœ… `transform` (translate, scale, rotate) -- βœ… `opacity` -- βœ… `filter` (with caution) - -**Avoid** (causes reflow/repaint): -- ❌ `width`, `height` -- ❌ `top`, `left`, `right`, `bottom` -- ❌ `margin`, `padding` - ---- - -## Common UI Animation Patterns - -### Button Interactions - -```css -/* Hover - subtle lift */ -.button { - transition: transform 200ms ease-out, box-shadow 200ms ease-out; -} -.button:hover { - transform: translateY(-2px); - box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15); -} - -/* Press - scale down */ -.button:active { - transform: scale(0.95); - transition: transform 100ms ease-in; -} - -/* Ripple effect */ -@keyframes ripple { - from { - transform: scale(0); - opacity: 1; - } - to { - transform: scale(2); - opacity: 0; - } -} -.button::after { - animation: ripple 400ms ease-out; -} -``` - -**Micro-syntax**: -``` -buttonHover: 200ms ease-out [Y0β†’-2, shadowβ†—] -buttonPress: 100ms ease-in [S1β†’0.95] -ripple: 400ms ease-out [S0β†’2, Ξ±1β†’0] -``` - -### Card Interactions - -```css -/* Hover - lift and shadow */ -.card { - transition: transform 300ms ease-out, box-shadow 300ms ease-out; -} -.card:hover { - transform: translateY(-4px); - box-shadow: 0 12px 24px rgba(0, 0, 0, 0.15); -} - -/* Select - scale and highlight */ -.card.selected { - transform: scale(1.02); - background-color: var(--accent); - transition: all 200ms ease-out; -} -``` - -**Micro-syntax**: -``` -cardHover: 300ms ease-out [Y0β†’-4, shadowβ†—] -cardSelect: 200ms ease-out [S1β†’1.02, bgβ†’accent] -``` - -### Modal/Dialog Animations - -```css -/* Backdrop fade in */ -.modal-backdrop { - animation: fadeIn 300ms ease-out; -} -@keyframes fadeIn { - from { opacity: 0; } - to { opacity: 1; } -} - -/* Modal slide up and fade */ -.modal { - animation: slideUp 350ms ease-out; -} -@keyframes slideUp { - from { - transform: translateY(40px); - opacity: 0; - } - to { - transform: translateY(0); - opacity: 1; - } -} - -/* Modal exit */ -.modal.closing { - animation: slideDown 250ms ease-in; -} -@keyframes slideDown { - from { - transform: translateY(0); - opacity: 1; - } - to { - transform: translateY(40px); - opacity: 0; - } -} -``` - -**Micro-syntax**: -``` -backdrop: 300ms ease-out [Ξ±0β†’1] -modalEnter: 350ms ease-out [Y+40β†’0, Ξ±0β†’1] -modalExit: 250ms ease-in [Y0β†’+40, Ξ±1β†’0] -``` - -### Dropdown/Menu Animations - -```css -/* Dropdown slide and fade */ -.dropdown { - animation: dropdownOpen 200ms ease-out; - transform-origin: top; -} -@keyframes dropdownOpen { - from { - transform: scaleY(0.95); - opacity: 0; - } - to { - transform: scaleY(1); - opacity: 1; - } -} -``` - -**Micro-syntax**: -``` -dropdown: 200ms ease-out [scaleY0.95β†’1, Ξ±0β†’1] -``` - -### Sidebar/Drawer Animations - -```css -/* Sidebar slide in */ -.sidebar { - animation: slideInLeft 350ms ease-out; -} -@keyframes slideInLeft { - from { - transform: translateX(-280px); - opacity: 0; - } - to { - transform: translateX(0); - opacity: 1; - } -} - -/* Overlay fade */ -.overlay { - animation: overlayFade 300ms ease-out; -} -@keyframes overlayFade { - from { - opacity: 0; - backdrop-filter: blur(0); - } - to { - opacity: 1; - backdrop-filter: blur(4px); - } -} -``` - -**Micro-syntax**: -``` -sidebar: 350ms ease-out [X-280β†’0, Ξ±0β†’1] -overlay: 300ms ease-out [Ξ±0β†’1, blur0β†’4px] -``` - ---- - -## Message/Chat UI Animations - -### Message Entrance - -```css -/* User message - slide from right */ -.message-user { - animation: slideInRight 400ms ease-out; -} -@keyframes slideInRight { - from { - transform: translateX(10px) translateY(20px); - opacity: 0; - scale: 0.9; - } - to { - transform: translateX(0) translateY(0); - opacity: 1; - scale: 1; - } -} - -/* AI message - slide from left with bounce */ -.message-ai { - animation: slideInLeft 600ms cubic-bezier(0.68, -0.55, 0.265, 1.55); - animation-delay: 200ms; -} -@keyframes slideInLeft { - from { - transform: translateY(15px); - opacity: 0; - scale: 0.95; - } - to { - transform: translateY(0); - opacity: 1; - scale: 1; - } -} -``` - -**Micro-syntax**: -``` -userMsg: 400ms ease-out [Y+20β†’0, X+10β†’0, S0.9β†’1] -aiMsg: 600ms bounce [Y+15β†’0, S0.95β†’1] +200ms -``` - -### Typing Indicator - -```css -/* Typing dots animation */ -.typing-indicator span { - animation: typingDot 1400ms infinite; -} -.typing-indicator span:nth-child(2) { - animation-delay: 200ms; -} -.typing-indicator span:nth-child(3) { - animation-delay: 400ms; -} -@keyframes typingDot { - 0%, 60%, 100% { - transform: translateY(0); - opacity: 0.4; - } - 30% { - transform: translateY(-8px); - opacity: 1; - } -} -``` - -**Micro-syntax**: -``` -typing: 1400ms ∞ [YΒ±8, Ξ±0.4β†’1] stagger+200ms -``` - -### Status Indicators - -```css -/* Online status pulse */ -.status-online { - animation: pulse 2000ms infinite; -} -@keyframes pulse { - 0%, 100% { - opacity: 1; - scale: 1; - } - 50% { - opacity: 0.6; - scale: 1.05; - } -} -``` - -**Micro-syntax**: -``` -status: 2000ms ∞ [Ξ±1β†’0.6β†’1, S1β†’1.05β†’1] -``` - ---- - -## Form Input Animations - -### Focus States - -```css -/* Input focus - ring and scale */ -.input { - transition: all 200ms ease-out; -} -.input:focus { - transform: scale(1.01); - box-shadow: 0 0 0 3px var(--ring); -} - -/* Input blur - return to normal */ -.input:not(:focus) { - transition: all 150ms ease-in; -} -``` - -**Micro-syntax**: -``` -inputFocus: 200ms ease-out [S1β†’1.01, shadow+ring] -inputBlur: 150ms ease-in [S1.01β†’1, shadow-ring] -``` - -### Validation States - -```css -/* Error shake */ -.input-error { - animation: shake 400ms ease-in-out; -} -@keyframes shake { - 0%, 100% { transform: translateX(0); } - 25% { transform: translateX(-5px); } - 75% { transform: translateX(5px); } -} - -/* Success checkmark */ -.input-success::after { - animation: checkmark 600ms cubic-bezier(0.68, -0.55, 0.265, 1.55); -} -@keyframes checkmark { - from { - transform: scale(0) rotate(0deg); - opacity: 0; - } - to { - transform: scale(1.2) rotate(360deg); - opacity: 1; - } -} -``` - -**Micro-syntax**: -``` -error: 400ms ease-in-out [XΒ±5] shake -success: 600ms bounce [S0β†’1.2, R0β†’360Β°, Ξ±0β†’1] -``` - ---- - -## Loading States - -### Skeleton Screens - -```css -/* Skeleton shimmer */ -.skeleton { - animation: shimmer 2000ms infinite; - background: linear-gradient( - 90deg, - var(--muted) 0%, - var(--accent) 50%, - var(--muted) 100% - ); - background-size: 200% 100%; -} -@keyframes shimmer { - 0% { background-position: 200% 0; } - 100% { background-position: -200% 0; } -} -``` - -**Micro-syntax**: -``` -skeleton: 2000ms ∞ [bg: muted↔accent] -``` - -### Spinners - -```css -/* Circular spinner */ -.spinner { - animation: spin 1000ms linear infinite; -} -@keyframes spin { - from { transform: rotate(0deg); } - to { transform: rotate(360deg); } -} - -/* Pulsing dots */ -.loading-dots span { - animation: dotPulse 1500ms infinite; -} -.loading-dots span:nth-child(2) { animation-delay: 200ms; } -.loading-dots span:nth-child(3) { animation-delay: 400ms; } -@keyframes dotPulse { - 0%, 80%, 100% { opacity: 0.3; scale: 0.8; } - 40% { opacity: 1; scale: 1; } -} -``` - -**Micro-syntax**: -``` -spinner: 1000ms ∞ linear [R360Β°] -dotPulse: 1500ms ∞ [Ξ±0.3β†’1β†’0.3, S0.8β†’1β†’0.8] stagger+200ms -``` - -### Progress Bars - -```css -/* Indeterminate progress */ -.progress-bar { - animation: progress 2000ms ease-in-out infinite; -} -@keyframes progress { - 0% { transform: translateX(-100%); } - 50% { transform: translateX(0); } - 100% { transform: translateX(100%); } -} -``` - -**Micro-syntax**: -``` -progress: 2000ms ∞ ease-in-out [X-100%β†’0β†’100%] -``` - ---- - -## Scroll Animations - -### Scroll-Triggered Fade In - -```css -/* Fade in on scroll */ -.fade-in-on-scroll { - opacity: 0; - transform: translateY(40px); - transition: opacity 500ms ease-out, transform 500ms ease-out; -} -.fade-in-on-scroll.visible { - opacity: 1; - transform: translateY(0); -} -``` - -**Micro-syntax**: -``` -scrollFadeIn: 500ms ease-out [Y+40β†’0, Ξ±0β†’1] -``` - -### Auto-Scroll - -```css -/* Smooth scroll behavior */ -html { - scroll-behavior: smooth; -} - -/* Scroll hint animation */ -.scroll-hint { - animation: scrollHint 800ms infinite; - animation-iteration-count: 3; -} -@keyframes scrollHint { - 0%, 100% { transform: translateY(0); } - 50% { transform: translateY(5px); } -} -``` - -**Micro-syntax**: -``` -autoScroll: 400ms smooth -scrollHint: 800ms βˆžΓ—3 [YΒ±5] -``` - ---- - -## Page Transitions - -### Route Changes - -```css -/* Page fade out */ -.page-exit { - animation: fadeOut 200ms ease-in; -} -@keyframes fadeOut { - from { opacity: 1; } - to { opacity: 0; } -} - -/* Page fade in */ -.page-enter { - animation: fadeIn 300ms ease-out; -} -@keyframes fadeIn { - from { opacity: 0; } - to { opacity: 1; } -} -``` - -**Micro-syntax**: -``` -pageExit: 200ms ease-in [Ξ±1β†’0] -pageEnter: 300ms ease-out [Ξ±0β†’1] -``` - ---- - -## Micro-Interactions - -### Hover Effects - -```css -/* Link underline slide */ -.link { - position: relative; -} -.link::after { - content: ''; - position: absolute; - bottom: 0; - left: 0; - width: 0; - height: 2px; - background: currentColor; - transition: width 250ms ease-out; -} -.link:hover::after { - width: 100%; -} -``` - -**Micro-syntax**: -``` -linkHover: 250ms ease-out [width0β†’100%] -``` - -### Toggle Switches - -```css -/* Toggle slide */ -.toggle-switch { - transition: background-color 200ms ease-out; -} -.toggle-switch .thumb { - transition: transform 200ms ease-out; -} -.toggle-switch.on .thumb { - transform: translateX(20px); -} -``` - -**Micro-syntax**: -``` -toggle: 200ms ease-out [X0β†’20, bgβ†’accent] -``` - ---- - -## Animation Recipes - -### Chat UI Complete Animation System - -``` -## Core Message Flow -userMsg: 400ms ease-out [Y+20β†’0, X+10β†’0, S0.9β†’1] -aiMsg: 600ms bounce [Y+15β†’0, S0.95β†’1] +200ms -typing: 1400ms ∞ [YΒ±8, Ξ±0.4β†’1] stagger+200ms -status: 300ms ease-out [Ξ±0.6β†’1, S1β†’1.05β†’1] - -## Interface Transitions -sidebar: 350ms ease-out [X-280β†’0, Ξ±0β†’1] -overlay: 300ms [Ξ±0β†’1, blur0β†’4px] -input: 200ms [S1β†’1.01, shadow+ring] focus -input: 150ms [S1.01β†’1, shadow-ring] blur - -## Button Interactions -sendBtn: 150ms [S1β†’0.95β†’1, RΒ±2Β°] press -sendBtn: 200ms [S1β†’1.05, shadowβ†—] hover -ripple: 400ms [S0β†’2, Ξ±1β†’0] - -## Loading States -chatLoad: 500ms ease-out [Y+40β†’0, Ξ±0β†’1] -skeleton: 2000ms ∞ [bg: muted↔accent] -spinner: 1000ms ∞ linear [R360Β°] - -## Micro Interactions -msgHover: 200ms [Y0β†’-2, shadowβ†—] -msgSelect: 200ms [bgβ†’accent, S1β†’1.02] -error: 400ms [XΒ±5] shake -success: 600ms bounce [S0β†’1.2β†’1, R360Β°] - -## Scroll & Navigation -autoScroll: 400ms smooth -scrollHint: 800ms βˆžΓ—3 [YΒ±5] -``` - ---- - -## Best Practices - -### Do's βœ… - -- Keep animations under 400ms for most interactions -- Use `transform` and `opacity` for 60fps performance -- Provide purpose for every animation -- Use ease-out for entrances, ease-in for exits -- Test on low-end devices -- Respect `prefers-reduced-motion` -- Stagger animations for lists (50-100ms delay) -- Use consistent timing across similar interactions - -### Don'ts ❌ - -- Don't animate width/height (use scale instead) -- Don't use animations longer than 800ms -- Don't animate too many elements at once -- Don't use animations without purpose -- Don't ignore accessibility preferences -- Don't use jarring/distracting animations -- Don't animate on every interaction -- Don't use complex easing for simple interactions - ---- - -## Accessibility - -### Reduced Motion - -```css -/* Respect user preferences */ -@media (prefers-reduced-motion: reduce) { - *, - *::before, - *::after { - animation-duration: 0.01ms !important; - animation-iteration-count: 1 !important; - transition-duration: 0.01ms !important; - } -} -``` - -### Focus Indicators - -```css -/* Always animate focus states */ -:focus-visible { - outline: 2px solid var(--ring); - outline-offset: 2px; - transition: outline-offset 150ms ease-out; -} -``` - ---- - -## References - -- [Web Animation API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API) -- [CSS Easing Functions](https://easings.net/) -- [Animation Performance](https://web.dev/animations-guide/) -- [Reduced Motion](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-reduced-motion) diff --git a/.opencode/context/development/api-design.md b/.opencode/context/development/api-design.md deleted file mode 100644 index e48e950..0000000 --- a/.opencode/context/development/api-design.md +++ /dev/null @@ -1,384 +0,0 @@ -# API Design Patterns - -**Category**: development -**Purpose**: REST API design principles, GraphQL patterns, and API versioning strategies -**Used by**: opencoder - ---- - -## Overview - -This guide covers best practices for designing robust, scalable, and maintainable APIs, including REST, GraphQL, and versioning strategies. - -## REST API Design - -### 1. Resource-Based URLs - -**Use nouns, not verbs**: -``` -# Bad -GET /getUsers -POST /createUser -POST /updateUser/123 - -# Good -GET /users -POST /users -PUT /users/123 -PATCH /users/123 -DELETE /users/123 -``` - -### 2. HTTP Methods - -**Use appropriate HTTP methods**: -- `GET` - Retrieve resources (idempotent, safe) -- `POST` - Create new resources -- `PUT` - Replace entire resource (idempotent) -- `PATCH` - Partial update (idempotent) -- `DELETE` - Remove resource (idempotent) - -### 3. Status Codes - -**Use standard HTTP status codes**: -``` -2xx Success - 200 OK - Successful GET, PUT, PATCH - 201 Created - Successful POST - 204 No Content - Successful DELETE - -4xx Client Errors - 400 Bad Request - Invalid input - 401 Unauthorized - Missing/invalid auth - 403 Forbidden - Authenticated but not authorized - 404 Not Found - Resource doesn't exist - 409 Conflict - Resource conflict (e.g., duplicate) - 422 Unprocessable Entity - Validation errors - -5xx Server Errors - 500 Internal Server Error - Unexpected error - 503 Service Unavailable - Temporary unavailability -``` - -### 4. Consistent Response Format - -**Standardize response structure**: -```json -// Success response -{ - "data": { - "id": "123", - "name": "John Doe", - "email": "john@example.com" - }, - "meta": { - "timestamp": "2024-01-01T00:00:00Z" - } -} - -// Error response -{ - "error": { - "code": "VALIDATION_ERROR", - "message": "Invalid input data", - "details": [ - { - "field": "email", - "message": "Invalid email format" - } - ] - }, - "meta": { - "timestamp": "2024-01-01T00:00:00Z", - "requestId": "abc-123" - } -} - -// Collection response -{ - "data": [...], - "meta": { - "total": 100, - "page": 1, - "pageSize": 20, - "totalPages": 5 - }, - "links": { - "self": "/users?page=1", - "next": "/users?page=2", - "prev": null, - "first": "/users?page=1", - "last": "/users?page=5" - } -} -``` - -### 5. Filtering, Sorting, Pagination - -**Support common query operations**: -``` -# Filtering -GET /users?status=active&role=admin - -# Sorting -GET /users?sort=createdAt:desc,name:asc - -# Pagination -GET /users?page=2&pageSize=20 - -# Field selection -GET /users?fields=id,name,email - -# Search -GET /users?q=john -``` - -### 6. Nested Resources - -**Handle relationships appropriately**: -``` -# Good - Shallow nesting -GET /users/123/posts -GET /posts?userId=123 - -# Avoid - Deep nesting -GET /users/123/posts/456/comments/789 -# Better -GET /comments/789 -``` - -## GraphQL Patterns - -### 1. Schema Design - -**Design clear, intuitive schemas**: -```graphql -type User { - id: ID! - name: String! - email: String! - posts: [Post!]! - createdAt: DateTime! -} - -type Post { - id: ID! - title: String! - content: String! - author: User! - comments: [Comment!]! - publishedAt: DateTime -} - -type Query { - user(id: ID!): User - users(filter: UserFilter, page: Int, pageSize: Int): UserConnection! - post(id: ID!): Post -} - -type Mutation { - createUser(input: CreateUserInput!): User! - updateUser(id: ID!, input: UpdateUserInput!): User! - deleteUser(id: ID!): Boolean! -} - -input CreateUserInput { - name: String! - email: String! -} - -input UserFilter { - status: UserStatus - role: UserRole - search: String -} -``` - -### 2. Resolver Patterns - -**Implement efficient resolvers**: -```javascript -const resolvers = { - Query: { - user: async (_, { id }, { dataSources }) => { - return dataSources.userAPI.getUser(id); - }, - users: async (_, { filter, page, pageSize }, { dataSources }) => { - return dataSources.userAPI.getUsers({ filter, page, pageSize }); - } - }, - - User: { - posts: async (user, _, { dataSources }) => { - // Use DataLoader to batch requests - return dataSources.postAPI.getPostsByUserId(user.id); - } - }, - - Mutation: { - createUser: async (_, { input }, { dataSources, user }) => { - // Check authorization - if (!user) throw new AuthenticationError('Not authenticated'); - - // Validate input - const validatedInput = validateUserInput(input); - - // Create user - return dataSources.userAPI.createUser(validatedInput); - } - } -}; -``` - -### 3. DataLoader for N+1 Prevention - -**Batch and cache database queries**: -```javascript -import DataLoader from 'dataloader'; - -const userLoader = new DataLoader(async (userIds) => { - const users = await db.users.findMany({ - where: { id: { in: userIds } } - }); - - // Return in same order as input - return userIds.map(id => users.find(u => u.id === id)); -}); - -// Usage in resolver -const user = await userLoader.load(userId); -``` - -## API Versioning - -### 1. URL Versioning - -**Version in the URL path**: -``` -GET /v1/users -GET /v2/users -``` - -**Pros**: Clear, easy to route -**Cons**: URL changes, harder to maintain multiple versions - -### 2. Header Versioning - -**Version in Accept header**: -``` -GET /users -Accept: application/vnd.myapi.v2+json -``` - -**Pros**: Clean URLs, flexible -**Cons**: Less visible, harder to test - -### 3. Deprecation Strategy - -**Communicate deprecation clearly**: -```javascript -// Response headers -Deprecation: true -Sunset: Sat, 31 Dec 2024 23:59:59 GMT -Link: ; rel="successor-version" - -// Response body -{ - "data": {...}, - "meta": { - "deprecated": true, - "deprecationDate": "2024-12-31", - "migrationGuide": "https://docs.example.com/migration/v1-to-v2" - } -} -``` - -## Authentication & Authorization - -### 1. JWT Tokens - -**Use JWT for stateless auth**: -```javascript -// Token structure -{ - "sub": "user-123", - "email": "user@example.com", - "role": "admin", - "iat": 1516239022, - "exp": 1516242622 -} - -// Middleware -function authenticateToken(req, res, next) { - const token = req.headers.authorization?.split(' ')[1]; - - if (!token) { - return res.status(401).json({ error: 'No token provided' }); - } - - try { - const decoded = jwt.verify(token, process.env.JWT_SECRET); - req.user = decoded; - next(); - } catch (error) { - return res.status(401).json({ error: 'Invalid token' }); - } -} -``` - -### 2. Role-Based Access Control - -**Implement RBAC**: -```javascript -function authorize(...roles) { - return (req, res, next) => { - if (!req.user) { - return res.status(401).json({ error: 'Not authenticated' }); - } - - if (!roles.includes(req.user.role)) { - return res.status(403).json({ error: 'Insufficient permissions' }); - } - - next(); - }; -} - -// Usage -app.delete('/users/:id', - authenticateToken, - authorize('admin'), - deleteUser -); -``` - -## Best Practices - -1. **Use HTTPS everywhere** - Encrypt all API traffic -2. **Implement rate limiting** - Prevent abuse and ensure fair usage -3. **Validate all inputs** - Never trust client data -4. **Use proper error handling** - Return meaningful error messages -5. **Document your API** - Use OpenAPI/Swagger or GraphQL introspection -6. **Version your API** - Plan for breaking changes -7. **Implement CORS properly** - Configure allowed origins carefully -8. **Log requests and errors** - Enable debugging and monitoring -9. **Use caching** - Implement ETags, Cache-Control headers -10. **Test thoroughly** - Unit, integration, and contract tests - -## Anti-Patterns - -- ❌ **Exposing internal IDs** - Use UUIDs or opaque identifiers -- ❌ **Returning too much data** - Support field selection -- ❌ **Ignoring idempotency** - PUT/PATCH/DELETE should be idempotent -- ❌ **Inconsistent naming** - Use camelCase or snake_case consistently -- ❌ **Missing pagination** - Always paginate collections -- ❌ **No rate limiting** - Protect against abuse -- ❌ **Verbose error messages** - Don't leak implementation details -- ❌ **Synchronous long operations** - Use async jobs for long tasks - -## References - -- REST API Design Rulebook by Mark Masse -- GraphQL Best Practices (graphql.org) -- API Design Patterns by JJ Geewax -- OpenAPI Specification (swagger.io) diff --git a/.opencode/context/development/clean-code.md b/.opencode/context/development/clean-code.md deleted file mode 100644 index 7189d05..0000000 --- a/.opencode/context/development/clean-code.md +++ /dev/null @@ -1,176 +0,0 @@ -# Clean Code Principles - -**Category**: development -**Purpose**: Core coding standards and best practices for writing clean, maintainable code -**Used by**: frontend-specialist, devops-specialist, opencoder - ---- - -## Overview - -Clean code is code that is easy to read, understand, and maintain. It follows consistent patterns, uses meaningful names, and is well-organized. This guide provides principles and patterns for writing clean code across all languages. - -## Core Principles - -### 1. Meaningful Names - -**Use intention-revealing names**: -- Variable names should reveal intent -- Function names should describe what they do -- Class names should describe what they represent - -**Examples**: -```javascript -// Bad -const d = new Date(); -const x = getUserData(); - -// Good -const currentDate = new Date(); -const activeUserProfile = getUserData(); -``` - -### 2. Functions Should Do One Thing - -**Single Responsibility**: -- Each function should have one clear purpose -- Functions should be small (ideally < 20 lines) -- Extract complex logic into separate functions - -**Example**: -```javascript -// Bad -function processUser(user) { - validateUser(user); - saveToDatabase(user); - sendEmail(user); - logActivity(user); -} - -// Good -function processUser(user) { - const validatedUser = validateUser(user); - const savedUser = saveUserToDatabase(validatedUser); - notifyUser(savedUser); - return savedUser; -} -``` - -### 3. Avoid Deep Nesting - -**Keep nesting shallow**: -- Use early returns -- Extract nested logic into functions -- Prefer guard clauses - -**Example**: -```javascript -// Bad -function processOrder(order) { - if (order) { - if (order.items.length > 0) { - if (order.total > 0) { - // process order - } - } - } -} - -// Good -function processOrder(order) { - if (!order) return; - if (order.items.length === 0) return; - if (order.total <= 0) return; - - // process order -} -``` - -### 4. DRY (Don't Repeat Yourself) - -**Eliminate duplication**: -- Extract common logic into reusable functions -- Use composition over inheritance -- Create utility functions for repeated patterns - -### 5. Error Handling - -**Handle errors explicitly**: -- Use try-catch for expected errors -- Provide meaningful error messages -- Don't ignore errors silently - -**Example**: -```javascript -// Bad -function fetchData() { - try { - return api.getData(); - } catch (e) { - return null; - } -} - -// Good -async function fetchData() { - try { - return await api.getData(); - } catch (error) { - logger.error('Failed to fetch data', { error }); - throw new DataFetchError('Unable to retrieve data', { cause: error }); - } -} -``` - -## Best Practices - -1. **Write self-documenting code** - Code should explain itself through clear naming and structure -2. **Keep functions pure when possible** - Avoid side effects, return new values instead of mutating -3. **Use consistent formatting** - Follow language-specific style guides (Prettier, ESLint, etc.) -4. **Write tests first** - TDD helps design better APIs and catch issues early -5. **Refactor regularly** - Improve code structure as you learn more about the domain -6. **Comment why, not what** - Code shows what, comments explain why -7. **Use type systems** - TypeScript, type hints, or static analysis tools -8. **Favor composition** - Build complex behavior from simple, reusable pieces - -## Anti-Patterns - -- ❌ **Magic numbers** - Use named constants instead of hardcoded values -- ❌ **God objects** - Classes that do too much or know too much -- ❌ **Premature optimization** - Optimize for readability first, performance second -- ❌ **Clever code** - Simple and clear beats clever and complex -- ❌ **Long parameter lists** - Use objects or configuration patterns instead -- ❌ **Boolean flags** - Often indicate a function doing multiple things -- ❌ **Mutable global state** - Leads to unpredictable behavior and bugs - -## Language-Specific Guidelines - -### JavaScript/TypeScript -- Use `const` by default, `let` when needed, never `var` -- Prefer arrow functions for callbacks -- Use async/await over raw promises -- Destructure objects and arrays for clarity - -### Python -- Follow PEP 8 style guide -- Use list comprehensions for simple transformations -- Prefer context managers (`with` statements) -- Use type hints for function signatures - -### Go -- Follow effective Go guidelines -- Use defer for cleanup -- Handle errors explicitly -- Keep interfaces small - -### Rust -- Embrace ownership and borrowing -- Use pattern matching -- Prefer iterators over loops -- Handle errors with Result types - -## References - -- Clean Code by Robert C. Martin -- The Pragmatic Programmer by Hunt & Thomas -- Refactoring by Martin Fowler diff --git a/.opencode/context/development/design-assets.md b/.opencode/context/development/design-assets.md deleted file mode 100644 index 6f5b074..0000000 --- a/.opencode/context/development/design-assets.md +++ /dev/null @@ -1,567 +0,0 @@ - -# Design Assets - -## Overview - -Guidelines for images, icons, fonts, and other design assets in frontend development. Focus on using reliable CDN sources and placeholder services. - -## Quick Reference - -**Images**: Unsplash, placehold.co (never make up URLs) -**Icons**: Lucide (default), Heroicons, Font Awesome -**Fonts**: Google Fonts -**CDN**: Use established CDN services only - ---- - -## Image Guidelines - -### Placeholder Images - -**Rule**: NEVER make up image URLs. Always use known placeholder services. - -#### Unsplash (Recommended) - -**Random Images**: -```html - -Random image - - -Nature image -Technology image -People image -``` - -**Categories Available**: -- nature, landscape, mountains, ocean, forest -- technology, computer, code, workspace -- people, portrait, business, team -- food, coffee, restaurant -- architecture, building, interior -- travel, city, street -- abstract, pattern, texture - -**Specific Images**: -```html - -Mountain landscape -``` - -#### Placehold.co - -**Simple Placeholders**: -```html - -Placeholder - - -Placeholder - - -Product placeholder - - -PNG placeholder -JPG placeholder -WebP placeholder -``` - -#### Picsum Photos - -**Random Photos**: -```html - -Random photo - - -Specific photo - - -Grayscale photo - - -Blurred photo -``` - -### Image Best Practices - -```html - -Nature landscape - - - - - - - - - Responsive nature image - -``` - ---- - -## Icon Systems - -### Lucide Icons (Recommended Default) - -**Loading**: -```html - - - - - -``` - -**Usage**: -```html - - - - - - - - - - - - - - - -``` - -**Common Icons**: -``` -Navigation: home, menu, x, chevron-down, chevron-up, arrow-left, arrow-right -User: user, user-plus, users, user-check, user-x -Actions: edit, trash, save, download, upload, share, copy -Communication: mail, message-circle, phone, send -Media: image, video, music, file, folder -UI: search, settings, bell, heart, star, bookmark -Status: check, x, alert-circle, info, help-circle -``` - -### Heroicons - -**Loading**: -```html - - -``` - -**Usage**: -```html - - - - - - - - - -``` - -### Font Awesome - -**Loading**: -```html - - -``` - -**Usage**: -```html - - - - - - - - - - - - - - - - - -``` - -### Icon Best Practices - -```html - - - - - - - Visit website - - - - - - -
- - Featured -
-``` - ---- - -## Font Loading - -### Google Fonts (Recommended) - -**Loading**: -```html - - - - - - - - - -``` - -**Usage**: -```css -body { - font-family: 'Inter', sans-serif; -} - -code, pre { - font-family: 'JetBrains Mono', monospace; -} -``` - -**Popular Font Combinations**: - -```html - - - - - - - - - - - -``` - -### Font Loading Strategies - -```html - - - - - - - - -``` - ---- - -## CDN Resources - -### CSS Frameworks - -```html - - - - - - - - - - -``` - -### JavaScript Libraries - -```html - - - - - - - - -``` - -### Utility Libraries - -```html - - - - - - -``` - ---- - -## SVG Assets - -### Inline SVG - -```html - - - - - - - - - -``` - -### SVG Backgrounds - -```html - -
-``` - ---- - -## Video Assets - -### Placeholder Videos - -```html - - - - - -``` - ---- - -## Asset Organization - -### File Structure - -``` -design_iterations/ -β”œβ”€β”€ theme_1.css -β”œβ”€β”€ ui_1.html -β”œβ”€β”€ ui_1_1.html (iteration) -β”œβ”€β”€ ui_1_2.html (iteration) -β”œβ”€β”€ dashboard_1.html -└── assets/ - β”œβ”€β”€ images/ - β”œβ”€β”€ icons/ - └── fonts/ -``` - -### Naming Conventions - -**Design Files**: -- Initial: `{design_name}_1.html` (e.g., `table_1.html`) -- Iterations: `{design_name}_1_1.html`, `{design_name}_1_2.html` -- Theme files: `theme_1.css`, `theme_2.css` - -**Asset Files**: -- Images: `hero-image.jpg`, `product-1.png` -- Icons: `logo.svg`, `icon-menu.svg` -- Fonts: `inter-var.woff2`, `jetbrains-mono.woff2` - ---- - -## Performance Optimization - -### Image Optimization - -```html - -Description - - - - - - Description - - - -Description -``` - -### Font Optimization - -```html - - - - - -``` - -### CDN Best Practices - -```html - - - - - -``` - ---- - -## Best Practices - -### Do's βœ… - -- Use established placeholder services (Unsplash, placehold.co) -- Always provide alt text for images -- Use Lucide as default icon library -- Load fonts from Google Fonts -- Use lazy loading for images -- Provide responsive image srcsets -- Use semantic SVG with accessible labels -- Specify CDN versions for stability -- Optimize images before deployment -- Use modern image formats (WebP, AVIF) - -### Don'ts ❌ - -- Don't make up image URLs -- Don't use images without alt text -- Don't load unnecessary icon libraries -- Don't use too many font families (2-3 max) -- Don't skip lazy loading -- Don't use unoptimized images -- Don't forget ARIA labels for icon buttons -- Don't use latest CDN versions in production -- Don't load fonts synchronously -- Don't use decorative images in content - ---- - -## Accessibility - -### Image Accessibility - -```html - -Sales increased 25% in Q4 2024 - - - - - -
- System architecture diagram -
- The diagram shows three layers: frontend, API, and database. -
-
-``` - -### Icon Accessibility - -```html - - - - - - - - -``` - ---- - -## References - -- [Unsplash Source](https://source.unsplash.com/) -- [Placehold.co](https://placehold.co/) -- [Lucide Icons](https://lucide.dev/) -- [Google Fonts](https://fonts.google.com/) -- [Web.dev Image Optimization](https://web.dev/fast/#optimize-your-images) diff --git a/.opencode/context/development/design-systems.md b/.opencode/context/development/design-systems.md deleted file mode 100644 index 14a3b6f..0000000 --- a/.opencode/context/development/design-systems.md +++ /dev/null @@ -1,381 +0,0 @@ - -# Design Systems - -## Overview - -This context file provides reusable design system patterns, theme templates, and color systems for frontend design work. Use these as starting points for creating cohesive, professional UI designs. - -## Quick Reference - -**Color Format**: OKLCH (perceptually uniform color space) -**Theme Variables**: CSS custom properties (--variable-name) -**Font Sources**: Google Fonts -**Responsive**: All designs must be mobile-first responsive - ---- - -## Theme Patterns - -### Neo-Brutalism Style - -**Characteristics**: 90s web design aesthetic, bold borders, flat shadows, high contrast - -**Use Cases**: -- Retro/vintage applications -- Bold, statement-making interfaces -- Art/creative portfolios -- Playful consumer apps - -**Theme Template**: - -```css -:root { - /* Colors - High contrast, bold */ - --background: oklch(1.0000 0 0); - --foreground: oklch(0 0 0); - --card: oklch(1.0000 0 0); - --card-foreground: oklch(0 0 0); - --popover: oklch(1.0000 0 0); - --popover-foreground: oklch(0 0 0); - --primary: oklch(0.6489 0.2370 26.9728); - --primary-foreground: oklch(1.0000 0 0); - --secondary: oklch(0.9680 0.2110 109.7692); - --secondary-foreground: oklch(0 0 0); - --muted: oklch(0.9551 0 0); - --muted-foreground: oklch(0.3211 0 0); - --accent: oklch(0.5635 0.2408 260.8178); - --accent-foreground: oklch(1.0000 0 0); - --destructive: oklch(0 0 0); - --destructive-foreground: oklch(1.0000 0 0); - --border: oklch(0 0 0); - --input: oklch(0 0 0); - --ring: oklch(0.6489 0.2370 26.9728); - - /* Chart colors */ - --chart-1: oklch(0.6489 0.2370 26.9728); - --chart-2: oklch(0.9680 0.2110 109.7692); - --chart-3: oklch(0.5635 0.2408 260.8178); - --chart-4: oklch(0.7323 0.2492 142.4953); - --chart-5: oklch(0.5931 0.2726 328.3634); - - /* Sidebar */ - --sidebar: oklch(0.9551 0 0); - --sidebar-foreground: oklch(0 0 0); - --sidebar-primary: oklch(0.6489 0.2370 26.9728); - --sidebar-primary-foreground: oklch(1.0000 0 0); - --sidebar-accent: oklch(0.5635 0.2408 260.8178); - --sidebar-accent-foreground: oklch(1.0000 0 0); - --sidebar-border: oklch(0 0 0); - --sidebar-ring: oklch(0.6489 0.2370 26.9728); - - /* Typography */ - --font-sans: DM Sans, sans-serif; - --font-serif: ui-serif, Georgia, Cambria, "Times New Roman", Times, serif; - --font-mono: Space Mono, monospace; - - /* Border radius - Sharp corners */ - --radius: 0px; - --radius-sm: calc(var(--radius) - 4px); - --radius-md: calc(var(--radius) - 2px); - --radius-lg: var(--radius); - --radius-xl: calc(var(--radius) + 4px); - - /* Shadows - Bold, offset shadows */ - --shadow-2xs: 4px 4px 0px 0px hsl(0 0% 0% / 0.50); - --shadow-xs: 4px 4px 0px 0px hsl(0 0% 0% / 0.50); - --shadow-sm: 4px 4px 0px 0px hsl(0 0% 0% / 1.00), 4px 1px 2px -1px hsl(0 0% 0% / 1.00); - --shadow: 4px 4px 0px 0px hsl(0 0% 0% / 1.00), 4px 1px 2px -1px hsl(0 0% 0% / 1.00); - --shadow-md: 4px 4px 0px 0px hsl(0 0% 0% / 1.00), 4px 2px 4px -1px hsl(0 0% 0% / 1.00); - --shadow-lg: 4px 4px 0px 0px hsl(0 0% 0% / 1.00), 4px 4px 6px -1px hsl(0 0% 0% / 1.00); - --shadow-xl: 4px 4px 0px 0px hsl(0 0% 0% / 1.00), 4px 8px 10px -1px hsl(0 0% 0% / 1.00); - --shadow-2xl: 4px 4px 0px 0px hsl(0 0% 0% / 2.50); - - /* Spacing */ - --tracking-normal: 0em; - --spacing: 0.25rem; -} -``` - ---- - -### Modern Dark Mode Style - -**Characteristics**: Clean, minimal, professional (Vercel/Linear aesthetic) - -**Use Cases**: -- SaaS applications -- Developer tools -- Professional dashboards -- Enterprise applications -- Modern web apps - -**Theme Template**: - -```css -:root { - /* Colors - Subtle, professional */ - --background: oklch(1 0 0); - --foreground: oklch(0.1450 0 0); - --card: oklch(1 0 0); - --card-foreground: oklch(0.1450 0 0); - --popover: oklch(1 0 0); - --popover-foreground: oklch(0.1450 0 0); - --primary: oklch(0.2050 0 0); - --primary-foreground: oklch(0.9850 0 0); - --secondary: oklch(0.9700 0 0); - --secondary-foreground: oklch(0.2050 0 0); - --muted: oklch(0.9700 0 0); - --muted-foreground: oklch(0.5560 0 0); - --accent: oklch(0.9700 0 0); - --accent-foreground: oklch(0.2050 0 0); - --destructive: oklch(0.5770 0.2450 27.3250); - --destructive-foreground: oklch(1 0 0); - --border: oklch(0.9220 0 0); - --input: oklch(0.9220 0 0); - --ring: oklch(0.7080 0 0); - - /* Chart colors - Monochromatic blues */ - --chart-1: oklch(0.8100 0.1000 252); - --chart-2: oklch(0.6200 0.1900 260); - --chart-3: oklch(0.5500 0.2200 263); - --chart-4: oklch(0.4900 0.2200 264); - --chart-5: oklch(0.4200 0.1800 266); - - /* Sidebar */ - --sidebar: oklch(0.9850 0 0); - --sidebar-foreground: oklch(0.1450 0 0); - --sidebar-primary: oklch(0.2050 0 0); - --sidebar-primary-foreground: oklch(0.9850 0 0); - --sidebar-accent: oklch(0.9700 0 0); - --sidebar-accent-foreground: oklch(0.2050 0 0); - --sidebar-border: oklch(0.9220 0 0); - --sidebar-ring: oklch(0.7080 0 0); - - /* Typography - System fonts */ - --font-sans: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, 'Noto Sans', sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji'; - --font-serif: ui-serif, Georgia, Cambria, "Times New Roman", Times, serif; - --font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace; - - /* Border radius - Rounded */ - --radius: 0.625rem; - --radius-sm: calc(var(--radius) - 4px); - --radius-md: calc(var(--radius) - 2px); - --radius-lg: var(--radius); - --radius-xl: calc(var(--radius) + 4px); - - /* Shadows - Subtle, soft */ - --shadow-2xs: 0 1px 3px 0px hsl(0 0% 0% / 0.05); - --shadow-xs: 0 1px 3px 0px hsl(0 0% 0% / 0.05); - --shadow-sm: 0 1px 3px 0px hsl(0 0% 0% / 0.10), 0 1px 2px -1px hsl(0 0% 0% / 0.10); - --shadow: 0 1px 3px 0px hsl(0 0% 0% / 0.10), 0 1px 2px -1px hsl(0 0% 0% / 0.10); - --shadow-md: 0 1px 3px 0px hsl(0 0% 0% / 0.10), 0 2px 4px -1px hsl(0 0% 0% / 0.10); - --shadow-lg: 0 1px 3px 0px hsl(0 0% 0% / 0.10), 0 4px 6px -1px hsl(0 0% 0% / 0.10); - --shadow-xl: 0 1px 3px 0px hsl(0 0% 0% / 0.10), 0 8px 10px -1px hsl(0 0% 0% / 0.10); - --shadow-2xl: 0 1px 3px 0px hsl(0 0% 0% / 0.25); - - /* Spacing */ - --tracking-normal: 0em; - --spacing: 0.25rem; -} -``` - ---- - -## Typography System - -### Recommended Font Families - -**Monospace Fonts** (Code, technical interfaces): -- JetBrains Mono -- Fira Code -- Source Code Pro -- IBM Plex Mono -- Roboto Mono -- Space Mono -- Geist Mono - -**Sans-Serif Fonts** (UI, body text): -- Inter -- Roboto -- Open Sans -- Poppins -- Montserrat -- Outfit -- Plus Jakarta Sans -- DM Sans -- Geist -- Space Grotesk - -**Display/Decorative Fonts**: -- Oxanium -- Architects Daughter - -**Serif Fonts** (Editorial, formal): -- Merriweather -- Playfair Display -- Lora -- Source Serif Pro -- Libre Baskerville - -### Font Loading - -Always use Google Fonts for consistency and reliability: - -```html - - - -``` - ---- - -## Color System Guidelines - -### OKLCH Color Space - -Use OKLCH for perceptually uniform colors: -- **L** (Lightness): 0-1 (0 = black, 1 = white) -- **C** (Chroma): 0-0.4 (saturation) -- **H** (Hue): 0-360 (color angle) - -**Format**: `oklch(L C H)` - -**Example**: `oklch(0.6489 0.2370 26.9728)` = vibrant orange - -### Color Palette Rules - -1. **Avoid Bootstrap Blue**: Unless explicitly requested, avoid generic blue (#007bff) -2. **Semantic Colors**: Use meaningful color names (--primary, --destructive, --success) -3. **Contrast**: Ensure WCAG AA compliance (4.5:1 for text) -4. **Consistency**: Use theme variables, not hardcoded colors - -### Background/Foreground Pairing - -**Rule**: Background should contrast with content - -- Light component β†’ Dark background -- Dark component β†’ Light background -- Ensures visibility and visual hierarchy - ---- - -## Shadow System - -### Shadow Scales - -Shadows create depth and hierarchy: - -- `--shadow-2xs`: Minimal elevation (1-2px) -- `--shadow-xs`: Subtle lift (2-3px) -- `--shadow-sm`: Small cards (3-4px) -- `--shadow`: Default elevation (4-6px) -- `--shadow-md`: Medium cards (6-8px) -- `--shadow-lg`: Modals, dropdowns (8-12px) -- `--shadow-xl`: Floating panels (12-16px) -- `--shadow-2xl`: Maximum elevation (16-24px) - -### Shadow Styles - -**Soft Shadows** (Modern): -```css -box-shadow: 0 1px 3px 0px hsl(0 0% 0% / 0.10); -``` - -**Hard Shadows** (Neo-brutalism): -```css -box-shadow: 4px 4px 0px 0px hsl(0 0% 0% / 1.00); -``` - ---- - -## Spacing System - -### Base Unit - -Use `--spacing: 0.25rem` (4px) as base unit - -### Scale - -- 1x = 0.25rem (4px) -- 2x = 0.5rem (8px) -- 3x = 0.75rem (12px) -- 4x = 1rem (16px) -- 6x = 1.5rem (24px) -- 8x = 2rem (32px) -- 12x = 3rem (48px) -- 16x = 4rem (64px) - ---- - -## Border Radius System - -### Radius Scales - -```css ---radius-sm: calc(var(--radius) - 4px); ---radius-md: calc(var(--radius) - 2px); ---radius-lg: var(--radius); ---radius-xl: calc(var(--radius) + 4px); -``` - -### Common Values - -- **Sharp** (Neo-brutalism): `--radius: 0px` -- **Subtle** (Modern): `--radius: 0.375rem` (6px) -- **Rounded** (Friendly): `--radius: 0.625rem` (10px) -- **Pill** (Buttons): `--radius: 9999px` - ---- - -## Usage Guidelines - -### When to Use Each Theme - -**Neo-Brutalism**: -- βœ… Creative/artistic projects -- βœ… Retro/vintage aesthetics -- βœ… Bold, statement-making designs -- ❌ Enterprise/corporate applications -- ❌ Accessibility-critical interfaces - -**Modern Dark Mode**: -- βœ… SaaS applications -- βœ… Developer tools -- βœ… Professional dashboards -- βœ… Enterprise applications -- βœ… Accessibility-critical interfaces - -### Customization - -1. Start with a base theme template -2. Adjust primary/accent colors for brand -3. Modify radius for desired feel -4. Adjust shadows for depth preference -5. Test contrast ratios for accessibility - ---- - -## Best Practices - -βœ… **Use CSS custom properties** for all theme values -βœ… **Test in light and dark modes** if applicable -βœ… **Validate color contrast** (WCAG AA minimum) -βœ… **Use semantic color names** (--primary, not --blue) -βœ… **Load fonts from Google Fonts** for reliability -βœ… **Apply consistent spacing** using the spacing scale -βœ… **Test responsive behavior** at all breakpoints - -❌ **Don't hardcode colors** in components -❌ **Don't use generic blue** (#007bff) without reason -❌ **Don't mix color formats** (stick to OKLCH) -❌ **Don't skip contrast testing** -❌ **Don't use too many font families** (2-3 max) - ---- - -## References - -- [OKLCH Color Picker](https://oklch.com/) -- [Google Fonts](https://fonts.google.com/) -- [WCAG Contrast Checker](https://webaim.org/resources/contrastchecker/) -- [Tailwind CSS Colors](https://tailwindcss.com/docs/customizing-colors) diff --git a/.opencode/context/development/frontend/navigation.md b/.opencode/context/development/frontend/navigation.md index 3e8653a..c525649 100644 --- a/.opencode/context/development/frontend/navigation.md +++ b/.opencode/context/development/frontend/navigation.md @@ -2,41 +2,34 @@ **Purpose**: Client-side development patterns -**Status**: 🚧 Placeholder - Content coming soon - --- -## Planned Structure +## Structure ``` frontend/ β”œβ”€β”€ navigation.md -β”‚ -β”œβ”€β”€ react/ -β”‚ β”œβ”€β”€ navigation.md -β”‚ β”œβ”€β”€ hooks-patterns.md -β”‚ β”œβ”€β”€ component-architecture.md -β”‚ β”œβ”€β”€ performance.md -β”‚ └── tanstack/ -β”‚ β”œβ”€β”€ query-patterns.md -β”‚ β”œβ”€β”€ router-patterns.md -β”‚ └── table-patterns.md -β”‚ -β”œβ”€β”€ vue/ -β”‚ └── navigation.md -β”‚ -└── state-management/ +β”œβ”€β”€ when-to-delegate.md +└── react/ β”œβ”€β”€ navigation.md - β”œβ”€β”€ context-patterns.md - β”œβ”€β”€ zustand-patterns.md - └── redux-patterns.md + └── react-patterns.md ``` --- -## For Now +## Quick Routes -Use specialized navigation: `../ui-navigation.md` +| Task | Path | +|------|------| +| **When to delegate** | `when-to-delegate.md` | +| **React patterns** | `react/react-patterns.md` | +| **React navigation** | `react/navigation.md` | + +--- + +## By Framework + +**React** β†’ `react/` - Modern React patterns, hooks, component design --- diff --git a/.opencode/context/development/frontend/react/navigation.md b/.opencode/context/development/frontend/react/navigation.md new file mode 100644 index 0000000..114fee7 --- /dev/null +++ b/.opencode/context/development/frontend/react/navigation.md @@ -0,0 +1,19 @@ +# React Development + +**Purpose**: Modern React patterns, hooks, and component design + +--- + +## Files + +| File | Description | Priority | +|------|-------------|----------| +| [react-patterns.md](react-patterns.md) | React hooks, components, state management | high | + +--- + +## Related Context + +- **UI Styling** β†’ `../../../ui/web/ui-styling-standards.md` +- **Animations** β†’ `../../../ui/web/animation-patterns.md` +- **Clean Code** β†’ `../../principles/clean-code.md` diff --git a/.opencode/context/development/react-patterns.md b/.opencode/context/development/frontend/react/react-patterns.md similarity index 100% rename from .opencode/context/development/react-patterns.md rename to .opencode/context/development/frontend/react/react-patterns.md diff --git a/.opencode/context/development/frontend/when-to-delegate.md b/.opencode/context/development/frontend/when-to-delegate.md new file mode 100644 index 0000000..9235bae --- /dev/null +++ b/.opencode/context/development/frontend/when-to-delegate.md @@ -0,0 +1,468 @@ + +# When to Delegate to Frontend Specialist + +## Overview + +Clear decision criteria for when to delegate frontend/UI work to the **frontend-specialist** subagent vs. handling it directly. + +## Quick Reference + +**Delegate to frontend-specialist when**: +- UI/UX design work (wireframes, themes, animations) +- Design system implementation +- Complex responsive layouts +- Animation and micro-interactions +- Visual design iterations + +**Handle directly when**: +- Simple HTML/CSS edits +- Single component updates +- Bug fixes in existing UI +- Minor styling tweaks + +--- + +## Decision Matrix + +### βœ… DELEGATE to Frontend-Specialist + +| Scenario | Why Delegate | Example | +|----------|--------------|---------| +| **New UI design from scratch** | Needs staged workflow (layout β†’ theme β†’ animation β†’ implement) | "Create a landing page for our product" | +| **Design system work** | Requires ContextScout for standards, ExternalScout for UI libs | "Implement our design system with Tailwind + Shadcn" | +| **Complex responsive layouts** | Needs mobile-first approach across breakpoints | "Build a dashboard with sidebar, cards, and responsive grid" | +| **Animation implementation** | Requires animation patterns, performance optimization | "Add smooth transitions and micro-interactions to the UI" | +| **Multi-stage design iterations** | Needs versioning (design_iterations/ folder) | "Design a checkout flow with 3 steps" | +| **Theme creation** | Requires OKLCH colors, CSS custom properties | "Create a dark mode theme for the app" | +| **Component library integration** | Needs ExternalScout for current docs (Flowbite, Radix, etc.) | "Integrate Flowbite components into our app" | +| **Accessibility-focused UI** | Requires WCAG compliance, ARIA attributes | "Build an accessible form with proper labels and validation" | + +### ⚠️ HANDLE DIRECTLY (Don't Delegate) + +| Scenario | Why Direct | Example | +|----------|------------|---------| +| **Simple HTML edits** | Single file, straightforward change | "Change the button text from 'Submit' to 'Send'" | +| **Minor CSS tweaks** | Small styling adjustment | "Make the header padding 20px instead of 16px" | +| **Bug fixes** | Fixing existing code, not creating new design | "Fix the broken link in the footer" | +| **Content updates** | Changing text, images, or data | "Update the hero section copy" | +| **Single component updates** | Modifying one existing component | "Add a new prop to the Button component" | +| **Quick prototypes** | Throwaway code for testing | "Create a quick HTML mockup to test an idea" | + +--- + +## Delegation Checklist + +Before delegating to frontend-specialist, ensure: + +- [ ] **Task is UI/design focused** (not backend, logic, or data) +- [ ] **Task requires design expertise** (layout, theme, animations) +- [ ] **Task benefits from staged workflow** (layout β†’ theme β†’ animation β†’ implement) +- [ ] **Task needs context discovery** (design systems, UI libraries, standards) +- [ ] **User has approved the approach** (never delegate before approval) + +--- + +## How to Delegate + +### Step 1: Discover Context (Optional but Recommended) + +If you're unsure what context the frontend-specialist will need: + +```javascript +task( + subagent_type="ContextScout", + description="Find frontend design context", + prompt="Find design system standards, UI component patterns, animation guidelines, and responsive breakpoint conventions for frontend work." +) +``` + +### Step 2: Propose Approach + +Present a plan to the user: + +```markdown +## Implementation Plan + +**Task**: Create landing page with hero section, features grid, and CTA + +**Approach**: Delegate to frontend-specialist subagent + +**Why**: +- Requires design system implementation +- Needs responsive layout across breakpoints +- Includes animations and micro-interactions +- Benefits from staged workflow (layout β†’ theme β†’ animation β†’ implement) + +**Context Needed**: +- Design system standards (ui/web/design-systems.md) +- UI styling standards (ui/web/ui-styling-standards.md) +- Animation patterns (ui/web/animation-patterns.md) + +**Approval needed before proceeding.** +``` + +### Step 3: Get Approval + +Wait for explicit user approval before delegating. + +### Step 4: Delegate with Context + +**For simple delegation** (no session needed): + +```javascript +task( + subagent_type="frontend-specialist", + description="Create landing page design", + prompt="Context to load: + - .opencode/context/ui/web/design-systems.md + - .opencode/context/ui/web/ui-styling-standards.md + - .opencode/context/ui/web/animation-patterns.md + + Task: Create a landing page with: + - Hero section with headline, subheadline, CTA button + - Features grid (3 columns on desktop, 1 on mobile) + - Smooth scroll animations + + Requirements: + - Use Tailwind CSS + Flowbite + - Mobile-first responsive design + - Animations <400ms + - Save to design_iterations/landing_1.html + + Follow your staged workflow: + 1. Layout (ASCII wireframe) + 2. Theme (CSS theme file) + 3. Animation (micro-interactions) + 4. Implement (HTML file) + + Request approval between each stage." +) +``` + +**For complex delegation** (with session): + +Create session context file first, then delegate with session path. + +--- + +## Common Patterns + +### Pattern 1: New Landing Page + +**Trigger**: User asks for a new landing page, marketing page, or product page + +**Decision**: βœ… Delegate to frontend-specialist + +**Why**: Requires full design workflow (layout, theme, animations, implementation) + +**Example**: +``` +User: "Create a landing page for our SaaS product" +You: [Propose approach] β†’ [Get approval] β†’ [Delegate to frontend-specialist] +``` + +### Pattern 2: Design System Implementation + +**Trigger**: User wants to implement or update a design system + +**Decision**: βœ… Delegate to frontend-specialist + +**Why**: Needs ContextScout for standards, ExternalScout for UI library docs + +**Example**: +``` +User: "Implement our design system using Tailwind and Shadcn" +You: [Propose approach] β†’ [Get approval] β†’ [Delegate to frontend-specialist] +``` + +### Pattern 3: Component Library Integration + +**Trigger**: User wants to integrate a UI component library (Flowbite, Radix, etc.) + +**Decision**: βœ… Delegate to frontend-specialist + +**Why**: Requires ExternalScout for current docs, proper integration patterns + +**Example**: +``` +User: "Add Flowbite components to our app" +You: [Propose approach] β†’ [Get approval] β†’ [Delegate to frontend-specialist] +``` + +### Pattern 4: Animation Work + +**Trigger**: User wants animations, transitions, or micro-interactions + +**Decision**: βœ… Delegate to frontend-specialist + +**Why**: Requires animation patterns, performance optimization (<400ms) + +**Example**: +``` +User: "Add smooth animations to the dashboard" +You: [Propose approach] β†’ [Get approval] β†’ [Delegate to frontend-specialist] +``` + +### Pattern 5: Simple HTML Edit + +**Trigger**: User wants to change text, fix a link, or update content + +**Decision**: ⚠️ Handle directly (don't delegate) + +**Why**: Simple edit, no design work needed + +**Example**: +``` +User: "Change the button text to 'Get Started'" +You: [Edit the HTML file directly] +``` + +### Pattern 6: CSS Bug Fix + +**Trigger**: User reports a styling bug or broken layout + +**Decision**: ⚠️ Handle directly (don't delegate) + +**Why**: Bug fix, not new design work + +**Example**: +``` +User: "The header is overlapping the content on mobile" +You: [Read the CSS, fix the issue directly] +``` + +--- + +## Red Flags (Don't Delegate) + +❌ **User just wants a quick fix** β†’ Handle directly +❌ **Task is backend/logic focused** β†’ Wrong subagent (use coder-agent or handle directly) +❌ **Task is a single line change** β†’ Handle directly +❌ **Task is content update** β†’ Handle directly +❌ **Task is testing/validation** β†’ Wrong subagent (use tester) +❌ **Task is code review** β†’ Wrong subagent (use reviewer) + +--- + +## Green Flags (Delegate) + +βœ… **User wants a new UI design** β†’ Delegate +βœ… **Task involves design systems** β†’ Delegate +βœ… **Task requires responsive layouts** β†’ Delegate +βœ… **Task includes animations** β†’ Delegate +βœ… **Task needs UI library integration** β†’ Delegate +βœ… **Task benefits from staged workflow** β†’ Delegate +βœ… **Task requires design expertise** β†’ Delegate + +--- + +## Frontend-Specialist Capabilities + +**What it does well**: +- Create complete UI designs from scratch +- Implement design systems (Tailwind, Shadcn, Flowbite) +- Build responsive layouts (mobile-first) +- Add animations and micro-interactions +- Integrate UI component libraries +- Create themes with OKLCH colors +- Follow staged workflow (layout β†’ theme β†’ animation β†’ implement) +- Version designs (design_iterations/ folder) + +**What it doesn't do**: +- Backend logic or API integration +- Database queries or data processing +- Testing or validation +- Code review or refactoring +- Simple HTML/CSS edits (overkill) +- Content updates (just text changes) + +--- + +## Context Files Frontend-Specialist Uses + +The frontend-specialist will automatically load these via ContextScout: + +**Design System**: +- `ui/web/design-systems.md` - Theme templates, color systems +- `ui/web/ui-styling-standards.md` - Tailwind, Flowbite, responsive design +- `ui/web/design-assets.md` - Images, icons, fonts + +**Patterns**: +- `ui/web/animation-patterns.md` - Animation syntax, micro-interactions +- `development/frontend/react/react-patterns.md` - React patterns (if React project) + +**Workflows**: +- `core/workflows/design-iteration.md` - Design iteration workflow + +--- + +## Best Practices + +### Do's βœ… + +- βœ… **Propose before delegating** - Show user the plan first +- βœ… **Get approval** - Never delegate without user approval +- βœ… **Provide context** - List context files the subagent should load +- βœ… **Set clear requirements** - Specify design system, breakpoints, animations +- βœ… **Use staged workflow** - Let frontend-specialist follow its process +- βœ… **Trust the specialist** - It knows design patterns and best practices + +### Don'ts ❌ + +- ❌ **Don't delegate simple edits** - Handle directly for efficiency +- ❌ **Don't skip approval** - Always get user sign-off first +- ❌ **Don't delegate backend work** - Wrong subagent +- ❌ **Don't micromanage** - Let the specialist follow its workflow +- ❌ **Don't delegate without context** - Provide context files to load +- ❌ **Don't delegate bug fixes** - Handle directly unless it's a design issue + +--- + +## Examples + +### Example 1: Landing Page (Delegate) + +**User Request**: "Create a landing page for our SaaS product with a hero section, features, and pricing" + +**Your Response**: +```markdown +## Implementation Plan + +**Task**: Create SaaS landing page + +**Approach**: Delegate to frontend-specialist subagent + +**Why**: +- Requires full design workflow (layout, theme, animations) +- Needs responsive design across breakpoints +- Benefits from design system standards + +**Context Needed**: +- Design system standards +- UI styling standards +- Animation patterns + +**Approval needed before proceeding.** +``` + +**After Approval**: +```javascript +task( + subagent_type="frontend-specialist", + description="Create SaaS landing page", + prompt="Context to load: + - .opencode/context/ui/web/design-systems.md + - .opencode/context/ui/web/ui-styling-standards.md + - .opencode/context/ui/web/animation-patterns.md + + Task: Create a SaaS landing page with: + - Hero section (headline, subheadline, CTA) + - Features section (3-column grid) + - Pricing section (3 tiers) + - Footer + + Requirements: + - Tailwind CSS + Flowbite + - Mobile-first responsive + - Smooth scroll animations + - Modern design system + + Follow staged workflow and request approval between stages." +) +``` + +### Example 2: Button Text Change (Direct) + +**User Request**: "Change the 'Submit' button to say 'Send Message'" + +**Your Response**: +```markdown +I'll update the button text directly. +``` + +**Action**: Read the HTML file, edit the button text, done. No delegation needed. + +--- + +### Example 3: Design System Implementation (Delegate) + +**User Request**: "Implement our design system using Tailwind and Shadcn components" + +**Your Response**: +```markdown +## Implementation Plan + +**Task**: Implement design system with Tailwind + Shadcn + +**Approach**: Delegate to frontend-specialist subagent + +**Why**: +- Requires UI library integration (Shadcn) +- Needs ExternalScout for current Shadcn docs +- Benefits from design system standards + +**Context Needed**: +- Design system standards +- UI styling standards +- External docs (Shadcn) + +**Approval needed before proceeding.** +``` + +**After Approval**: +```javascript +task( + subagent_type="frontend-specialist", + description="Implement Tailwind + Shadcn design system", + prompt="Context to load: + - .opencode/context/ui/web/design-systems.md + - .opencode/context/ui/web/ui-styling-standards.md + + Task: Implement design system using Tailwind CSS and Shadcn/ui + + Requirements: + - Call ExternalScout for current Shadcn docs + - Set up Tailwind config + - Integrate Shadcn components + - Create theme file with OKLCH colors + - Document component usage + + Follow staged workflow and request approval between stages." +) +``` + +--- + +## Summary + +**Delegate to frontend-specialist when**: +- New UI designs from scratch +- Design system implementation +- Complex responsive layouts +- Animation work +- UI library integration +- Multi-stage design iterations + +**Handle directly when**: +- Simple HTML/CSS edits +- Bug fixes +- Content updates +- Single component updates +- Quick prototypes + +**Always**: +- Propose approach first +- Get user approval +- Provide context files +- Trust the specialist's workflow + +--- + +## Related Context + +- **Frontend Specialist Agent** β†’ `../../../agent/subagents/development/frontend-specialist.md` +- **Design Systems** β†’ `../../ui/web/design-systems.md` +- **UI Styling Standards** β†’ `../../ui/web/ui-styling-standards.md` +- **Animation Patterns** β†’ `../../ui/web/animation-patterns.md` +- **Delegation Workflow** β†’ `../../core/workflows/task-delegation.md` +- **React Patterns** β†’ `react/react-patterns.md` diff --git a/.opencode/context/development/navigation.md b/.opencode/context/development/navigation.md index aad1a57..25cc62b 100644 --- a/.opencode/context/development/navigation.md +++ b/.opencode/context/development/navigation.md @@ -26,11 +26,12 @@ development/ β”‚ β”œβ”€β”€ navigation.md β”‚ └── mastra-ai/ β”‚ -β”œβ”€β”€ frontend/ # Client-side (future) +β”œβ”€β”€ frontend/ # Client-side β”‚ β”œβ”€β”€ navigation.md -β”‚ β”œβ”€β”€ react/ -β”‚ β”œβ”€β”€ vue/ -β”‚ └── state-management/ +β”‚ β”œβ”€β”€ when-to-delegate.md # When to use frontend-specialist +β”‚ └── react/ +β”‚ β”œβ”€β”€ navigation.md +β”‚ └── react-patterns.md β”‚ β”œβ”€β”€ backend/ # Server-side (future) β”‚ β”œβ”€β”€ navigation.md @@ -64,6 +65,7 @@ development/ | Task | Path | |------|------| | **UI/Frontend** | `ui-navigation.md` | +| **When to delegate frontend** | `frontend/when-to-delegate.md` | | **Backend/API** | `backend-navigation.md` | | **Full-stack** | `fullstack-navigation.md` | | **Clean code** | `principles/clean-code.md` | @@ -76,7 +78,7 @@ development/ **Principles** β†’ Universal development practices **Frameworks** β†’ Full-stack frameworks (Tanstack Start, Next.js) **AI** β†’ AI frameworks and agent runtimes (MAStra AI) -**Frontend** β†’ React, Vue, state management (future) +**Frontend** β†’ React patterns and component design **Backend** β†’ APIs, Node.js, Python, auth (future) **Data** β†’ SQL, NoSQL, ORMs (future) **Integration** β†’ Packages, APIs, services (future) diff --git a/.opencode/context/development/ui-navigation.md b/.opencode/context/development/ui-navigation.md index f0d33b6..371eebd 100644 --- a/.opencode/context/development/ui-navigation.md +++ b/.opencode/context/development/ui-navigation.md @@ -8,13 +8,9 @@ ``` Frontend Code (development/frontend/): -β”œβ”€β”€ react/ # [future] -β”‚ β”œβ”€β”€ hooks-patterns.md -β”‚ β”œβ”€β”€ component-architecture.md -β”‚ └── tanstack/ -β”‚ β”œβ”€β”€ query-patterns.md -β”‚ └── router-patterns.md -└── vue/ # [future] +└── react/ + β”œβ”€β”€ navigation.md + └── react-patterns.md Visual Design (ui/web/): β”œβ”€β”€ animation-patterns.md @@ -31,8 +27,7 @@ Visual Design (ui/web/): | Task | Path | |------|------| -| **React patterns** | `frontend/react/hooks-patterns.md` [future] | -| **TanStack Query** | `frontend/react/tanstack/query-patterns.md` [future] | +| **React patterns** | `frontend/react/react-patterns.md` | | **Animations** | `../../ui/web/animation-patterns.md` | | **Styling** | `../../ui/web/ui-styling-standards.md` | | **Design systems** | `../../ui/web/design-systems.md` | @@ -41,13 +36,11 @@ Visual Design (ui/web/): ## By Framework -**React** β†’ `frontend/react/` [future] -**Vue** β†’ `frontend/vue/` [future] -**TanStack** β†’ `frontend/react/tanstack/` [future] +**React** β†’ `frontend/react/` ## By Concern -**Code patterns** β†’ `development/frontend/` [future] +**Code patterns** β†’ `development/frontend/` **Visual design** β†’ `ui/web/` --- diff --git a/.opencode/context/development/ui-styling-standards.md b/.opencode/context/development/ui-styling-standards.md deleted file mode 100644 index bafdd26..0000000 --- a/.opencode/context/development/ui-styling-standards.md +++ /dev/null @@ -1,552 +0,0 @@ - -# UI Styling Standards - -## Overview - -Standards and conventions for CSS frameworks, responsive design, and styling best practices in frontend development. - -## Quick Reference - -**Framework**: Tailwind CSS + Flowbite (default) -**Approach**: Mobile-first responsive -**Format**: Utility-first CSS -**Specificity**: Use `!important` for overrides when needed - ---- - -## CSS Framework Conventions - -### Tailwind CSS - -**Loading Method** (Preferred): - -```html - - -``` - -**Avoid**: - -```html - - -``` - -**Why**: Script tag allows for JIT compilation and configuration - -### Flowbite - -**Loading Method**: - -```html - - - - - -``` - -**Usage**: Flowbite is the default component library unless user specifies otherwise - -**Components Available**: -- Buttons, forms, modals -- Navigation, dropdowns, tabs -- Cards, alerts, badges -- Tables, pagination -- Tooltips, popovers - ---- - -## Responsive Design Requirements - -### Mobile-First Approach - -**Rule**: ALL designs MUST be responsive - -**Breakpoints** (Tailwind defaults): - -```css -/* Mobile first - base styles apply to mobile */ -.element { } - -/* Small devices (640px and up) */ -@media (min-width: 640px) { } /* sm: */ - -/* Medium devices (768px and up) */ -@media (min-width: 768px) { } /* md: */ - -/* Large devices (1024px and up) */ -@media (min-width: 1024px) { } /* lg: */ - -/* Extra large devices (1280px and up) */ -@media (min-width: 1280px) { } /* xl: */ - -/* 2XL devices (1536px and up) */ -@media (min-width: 1536px) { } /* 2xl: */ -``` - -**Tailwind Syntax**: - -```html - -
-
Left
-
Right
-
- - -
- Content -
-``` - -### Testing Requirements - -βœ… Test at minimum breakpoints: 375px, 768px, 1024px, 1440px -βœ… Verify touch targets (min 44x44px) -βœ… Check text readability at all sizes -βœ… Ensure images scale properly -βœ… Test navigation on mobile - ---- - -## Color Palette Guidelines - -### Avoid Bootstrap Blue - -**Rule**: NEVER use generic Bootstrap blue (#007bff) unless explicitly requested - -**Why**: Overused, lacks personality, feels dated - -**Alternatives**: - -```css -/* Instead of Bootstrap blue */ ---bootstrap-blue: #007bff; /* ❌ Avoid */ - -/* Use contextual colors */ ---primary: oklch(0.6489 0.2370 26.9728); /* Vibrant orange */ ---accent: oklch(0.5635 0.2408 260.8178); /* Rich purple */ ---info: oklch(0.6200 0.1900 260); /* Modern blue */ ---success: oklch(0.7323 0.2492 142.4953); /* Fresh green */ -``` - -### Color Usage Rules - -1. **Semantic naming**: Use `--primary`, `--accent`, not `--blue`, `--red` -2. **Brand alignment**: Choose colors that match project personality -3. **Contrast testing**: Ensure WCAG AA compliance (4.5:1 minimum) -4. **Consistency**: Use theme variables throughout - ---- - -## Background/Foreground Contrast - -### Contrast Rule - -**When designing components or posters**: - -- **Light component** β†’ Dark background -- **Dark component** β†’ Light background - -**Why**: Ensures visibility and creates visual hierarchy - -**Examples**: - -```html - -
-
- Light card content -
-
- - -
-
- Dark card content -
-
-``` - -### Component-Specific Rules - -**Posters/Hero Sections**: -- Use high contrast for readability -- Consider overlay gradients for text on images -- Test with actual content - -**Cards/Panels**: -- Subtle elevation with shadows -- Clear boundary between card and background -- Consistent padding - ---- - -## CSS Specificity & Overrides - -### Using !important - -**Rule**: Use `!important` for properties that might be overwritten by Tailwind or Flowbite - -**Common Cases**: - -```css -/* Typography overrides */ -h1 { - font-size: 2.5rem !important; - font-weight: 700 !important; - line-height: 1.2 !important; -} - -body { - font-family: 'Inter', sans-serif !important; - color: var(--foreground) !important; -} - -/* Component overrides */ -.custom-button { - background-color: var(--primary) !important; - border-radius: var(--radius) !important; -} -``` - -**When NOT to use**: - -```css -/* ❌ Don't use for everything */ -.element { - margin: 1rem !important; - padding: 1rem !important; - display: flex !important; -} - -/* βœ… Use Tailwind utilities instead */ -
-``` - -### Specificity Best Practices - -1. **Prefer utility classes** over custom CSS -2. **Use !important sparingly** - only for framework overrides -3. **Scope custom styles** to avoid conflicts -4. **Use CSS custom properties** for theming - ---- - -## Layout Patterns - -### Flexbox (Preferred for 1D layouts) - -```html - -
-
Item 1
-
Item 2
-
- - -
-
Item 1
-
Item 2
-
- - -
-
Centered content
-
-``` - -### Grid (Preferred for 2D layouts) - -```html - -
-
Card 1
-
Card 2
-
Card 3
-
- - -
- -
Content
-
-``` - -### Container Patterns - -```html - -
- Content -
- - -
-
- Content -
-
-``` - ---- - -## Typography Standards - -### Hierarchy - -```html - -

Main Heading

-

Section Heading

-

Subsection

-

Minor Heading

- - -

Body text

-

Secondary text

-

Caption text

-``` - -### Font Loading - -**Always use Google Fonts**: - -```html - - - -``` - -**Apply in CSS**: - -```css -body { - font-family: 'Inter', sans-serif !important; -} -``` - -### Readability - -- **Line length**: 60-80 characters optimal -- **Line height**: 1.5-1.75 for body text -- **Font size**: Minimum 16px for body text -- **Contrast**: 4.5:1 minimum for normal text - ---- - -## Component Styling Patterns - -### Buttons - -```html - - - - - - - - -``` - -### Cards - -```html - -
-

Card Title

-

Card content

-
- - -
-

Interactive Card

-

Hover for effect

-
-``` - -### Forms - -```html - -
- - -
- - -
- - -
-``` - ---- - -## Accessibility Standards - -### ARIA Labels - -```html - - - - - -``` - -### Semantic HTML - -```html - -
...
- -
...
-
...
- -
...
- - -
...
-
...
-
...
-``` - -### Focus States - -```css -/* Always provide visible focus states */ -button:focus-visible { - outline: 2px solid var(--ring); - outline-offset: 2px; -} - -/* Tailwind utility */ - -``` - ---- - -## Performance Optimization - -### CSS Loading - -```html - - - - - - -``` - -### Image Optimization - -```html - -Description -``` - -### Critical CSS - -```html - - - - - -``` - ---- - -## Best Practices - -### Do's βœ… - -- Use Tailwind utility classes for rapid development -- Load Tailwind via script tag for JIT compilation -- Use Flowbite as default component library -- Ensure all designs are mobile-first responsive -- Test at multiple breakpoints -- Use semantic HTML elements -- Provide ARIA labels for interactive elements -- Use CSS custom properties for theming -- Apply `!important` for framework overrides -- Ensure proper color contrast (WCAG AA) - -### Don'ts ❌ - -- Don't use Bootstrap blue without explicit request -- Don't load Tailwind as a stylesheet -- Don't skip responsive design -- Don't use div soup (use semantic HTML) -- Don't forget focus states -- Don't hardcode colors (use theme variables) -- Don't skip accessibility testing -- Don't use tiny touch targets (<44px) -- Don't mix color formats -- Don't over-use `!important` - ---- - -## Framework Alternatives - -If user requests a different framework: - -**Bootstrap**: -```html - - -``` - -**Bulma**: -```html - -``` - -**Foundation**: -```html - - -``` - ---- - -## References - -- [Tailwind CSS Documentation](https://tailwindcss.com/docs) -- [Flowbite Components](https://flowbite.com/docs/getting-started/introduction/) -- [WCAG Guidelines](https://www.w3.org/WAI/WCAG21/quickref/) -- [MDN Web Accessibility](https://developer.mozilla.org/en-US/docs/Web/Accessibility) diff --git a/.opencode/context/openagents-repo/lookup/file-locations.md b/.opencode/context/openagents-repo/lookup/file-locations.md index 221dc47..22fad70 100644 --- a/.opencode/context/openagents-repo/lookup/file-locations.md +++ b/.opencode/context/openagents-repo/lookup/file-locations.md @@ -210,7 +210,7 @@ evals/framework/src/types/ # TypeScript types **Examples**: - `.opencode/context/core/standards/code-quality.md` -- `.opencode/context/development/react-patterns.md` +- `.opencode/context/development/frontend/react/react-patterns.md` - `.opencode/context/content-creation/principles/copywriting-frameworks.md` ### Tests diff --git a/.opencode/profiles/developer/profile.json b/.opencode/profiles/developer/profile.json index 8f96d32..297af33 100644 --- a/.opencode/profiles/developer/profile.json +++ b/.opencode/profiles/developer/profile.json @@ -30,10 +30,10 @@ "context:core/*", "context:project-intelligence/*", "context:to-be-consumed/*", - "context:development/ui-styling-standards", - "context:development/design-systems", - "context:development/design-assets", - "context:development/animation-patterns", + "context:ui/web/ui-styling-standards", + "context:ui/web/design-systems", + "context:ui/web/design-assets", + "context:ui/web/animation-patterns", "config:env-example", "config:readme", "skill:context-manager", diff --git a/registry.json b/registry.json index 619fc70..7ca1294 100644 --- a/registry.json +++ b/registry.json @@ -2118,76 +2118,6 @@ "dependencies": [], "category": "standard" }, - { - "id": "design-assets", - "name": "Design Assets", - "type": "context", - "path": ".opencode/context/development/design-assets.md", - "description": "Design Assets", - "tags": [], - "dependencies": [], - "category": "standard" - }, - { - "id": "ui-styling-standards", - "name": "Ui Styling Standards", - "type": "context", - "path": ".opencode/context/development/ui-styling-standards.md", - "description": "UI Styling Standards", - "tags": [], - "dependencies": [], - "category": "standard" - }, - { - "id": "clean-code", - "name": "Clean Code", - "type": "context", - "path": ".opencode/context/development/clean-code.md", - "description": "Clean Code Principles", - "tags": [], - "dependencies": [], - "category": "standard" - }, - { - "id": "animation-patterns", - "name": "Animation Patterns", - "type": "context", - "path": ".opencode/context/development/animation-patterns.md", - "description": "Animation Patterns", - "tags": [], - "dependencies": [], - "category": "standard" - }, - { - "id": "design-systems", - "name": "Design Systems", - "type": "context", - "path": ".opencode/context/development/design-systems.md", - "description": "Design Systems", - "tags": [], - "dependencies": [], - "category": "standard" - }, - { - "id": "react-patterns", - "name": "React Patterns", - "type": "context", - "path": ".opencode/context/development/react-patterns.md", - "description": "React Patterns & Best Practices", - "tags": [], - "dependencies": [], - "category": "standard" - }, - { - "id": "api-design", - "name": "Api Design", - "type": "context", - "path": ".opencode/context/development/api-design.md", - "description": "API Design Patterns", - "tags": [], - "dependencies": [], - "category": "standard" - }, { "id": "mastra-config", "name": "Mastra Config", @@ -2615,18 +2545,6 @@ ], "category": "standard" }, - { - "id": "development-readme", - "name": "Development README", - "type": "context", - "path": ".opencode/context/development/README.md", - "description": "Development context overview and guide", - "tags": [ - "development", - "guide" - ], - "category": "standard" - }, { "id": "learning-readme", "name": "Learning README", @@ -2663,19 +2581,6 @@ ], "category": "standard" }, - { - "id": "mastra-ai-readme", - "name": "Mastra AI README", - "type": "context", - "path": ".opencode/context/development/ai/mastra-ai/README.md", - "description": "Mastra AI framework documentation and guides", - "tags": [ - "mastra-ai", - "ai", - "development" - ], - "category": "standard" - }, { "id": "context-bundle-template", "name": "Context Bundle Template", @@ -2773,7 +2678,7 @@ }, "developer": { "name": "Developer", - "description": "Complete software development environment with code generation, testing, review, and build tools. Use OpenAgent for general tasks (1-4 files) or OpenCoder for complex architecture (4+ files). Recommended for most developers.", + "description": "Complete software development environment with code generation, testing, review, and build tools. Includes UI/UX patterns, development principles, and design systems. Use OpenAgent for general tasks (1-4 files) or OpenCoder for complex architecture (4+ files). Recommended for most developers.", "badge": "RECOMMENDED", "components": [ "agent:openagent", @@ -2803,6 +2708,15 @@ "context:project-intelligence/*", "context:to-be-consumed/*", "context:adding-skill", + "context:ui/*", + "context:development/*", + "context:design-systems", + "context:react-patterns", + "context:animation-patterns", + "context:ui-styling-standards", + "context:design-assets", + "context:clean-code", + "context:api-design", "config:env-example", "config:readme" ] @@ -2839,7 +2753,7 @@ }, "full": { "name": "Full", - "description": "Everything included - all agents, subagents, tools, and plugins for maximum functionality.", + "description": "Everything included - all agents, subagents, tools, and plugins for maximum functionality. Includes UI/UX patterns, development principles, and design systems.", "components": [ "agent:openagent", "agent:opencoder", @@ -2877,13 +2791,22 @@ "context:project-intelligence/*", "context:to-be-consumed/*", "context:adding-skill", + "context:ui/*", + "context:development/*", + "context:design-systems", + "context:react-patterns", + "context:animation-patterns", + "context:ui-styling-standards", + "context:design-assets", + "context:clean-code", + "context:api-design", "config:env-example", "config:readme" ] }, "advanced": { "name": "Advanced (Meta-Level)", - "description": "Full installation plus System Builder for creating custom AI architectures. For power users and contributors.", + "description": "Full installation plus System Builder for creating custom AI architectures. Includes comprehensive context system, system builder templates, and repository management tools. For power users and contributors.", "components": [ "agent:openagent", "agent:opencoder", @@ -2930,6 +2853,25 @@ "context:project-intelligence/*", "context:to-be-consumed/*", "context:adding-skill", + "context:ui/*", + "context:development/*", + "context:design-systems", + "context:react-patterns", + "context:animation-patterns", + "context:ui-styling-standards", + "context:design-assets", + "context:clean-code", + "context:api-design", + "context:system-builder-guide", + "context:orchestrator-template", + "context:subagent-template", + "context:openagents-repo/*", + "context:context-system", + "context:context-system/*", + "context:registry-dependencies", + "context:templates", + "context:frontmatter", + "context:codebase-references", "config:env-example", "config:readme" ],