feat: enhance developer and advanced profiles with UI, development, and system builder context (#148)

* chore: bump version to v0.8.0

* chore: update version to 0.7.1 instead of 0.8.0

* docs: expand comparison table with Oh My OpenCode and additional features

* backup: development context before reorganization

* refactor(context): reorganize development folder

- Remove 7 duplicate files (ui/design files exist in ui/web/)
- Remove 2 redundant READMEs (use navigation.md instead)
- Move react-patterns.md to frontend/react/
- Create frontend/react/navigation.md
- Update 4 navigation files (development, ui, frontend, frontend/react)
- Update developer profile (4 path changes: ui-styling-standards, design-systems, design-assets, animation-patterns)
- Update 3 core context files (visual-development.md, design-iteration.md, file-locations.md)

Result: 29 context files (down from 36), no duplicates, clean structure

Refs: REORGANIZATION_PLAN.md, REORGANIZATION_SUMMARY.md

* docs(context): add frontend delegation guide

- Create when-to-delegate.md with clear decision criteria
- Decision matrix for when to delegate vs. handle directly
- Common patterns and examples
- Red flags and green flags
- Frontend-specialist capabilities reference
- Update frontend and development navigation files

Helps orchestrators decide when to delegate UI work to frontend-specialist subagent.

* feat: enhance developer and advanced profiles with UI, development, and system builder context

- Developer profile: Add UI/UX patterns, development principles, design systems, React patterns, animation patterns, styling standards, and design assets
- Full profile: Add same UI/development context as developer profile for consistency
- Advanced profile: Add comprehensive system builder context including templates, guides, context system standards, and repository management context
- Update profile descriptions to reflect new capabilities
- All context files verified to exist and are properly referenced

* fix: remove duplicate context entries with incorrect paths

- Remove duplicate design-assets, ui-styling-standards, clean-code, animation-patterns, design-systems, react-patterns, and api-design entries that pointed to wrong paths
- Remove non-existent development-readme and mastra-ai-readme entries
- Keep only correct entries with proper file paths
- All registry paths now validated and correct

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
This commit is contained in:
Darren Hinde 2026-01-30 22:21:12 +00:00 committed by GitHub
parent 38995b24c8
commit 7472575aaa
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
20 changed files with 615 additions and 3070 deletions

View file

@ -81,9 +81,16 @@ tags:
NEVER rely on training data for library APIs NEVER rely on training data for library APIs
</rule> </rule>
<rule id="output_format"> <rule id="output_format">
ALWAYS write files to .tmp/external-context/ BEFORE returning summary
ALWAYS return: file locations + brief summary + official docs link ALWAYS return: file locations + brief summary + official docs link
ALWAYS filter to relevant sections only ALWAYS filter to relevant sections only
NO reports, guides, or integration documentation NO reports, guides, or integration documentation
NEVER say "ready to be persisted" - files must be WRITTEN, not just fetched
</rule>
<rule id="mandatory_persistence">
You MUST write fetched documentation to files using the Write tool
Fetching without writing = FAILURE
Stage 4 (PersistToTemp) is MANDATORY and cannot be skipped
</rule> </rule>
</critical_rules> </critical_rules>
@ -93,19 +100,21 @@ tags:
<tier level="1" desc="Critical Operations"> <tier level="1" desc="Critical Operations">
- @tool_usage: Use ONLY allowed tools - @tool_usage: Use ONLY allowed tools
- @always_use_tools: Fetch from real sources - @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
</tier> </tier>
<tier level="2" desc="Core Workflow"> <tier level="2" desc="Core Workflow">
- Detect library from registry - Detect library from registry
- Fetch from Context7 (primary) - Fetch from Context7 (primary)
- Fallback to official docs (webfetch) - Fallback to official docs (webfetch)
- Filter to relevant sections - Filter to relevant sections
- Persist to .tmp/external-context/ - Persist to .tmp/external-context/ (CANNOT be skipped)
- Return file locations + summary - Return file locations + summary
</tier> </tier>
<conflict_resolution> <conflict_resolution>
Tier 1 always overrides Tier 2 Tier 1 always overrides Tier 2
If workflow conflicts w/ tool restrictions→abort and report error If workflow conflicts w/ tool restrictions→abort and report error
Stage 4 (PersistToTemp) is MANDATORY and cannot be skipped under any circumstances
</conflict_resolution> </conflict_resolution>
</execution_priority> </execution_priority>
@ -150,12 +159,14 @@ tags:
<checkpoint>Results filtered to relevant content only</checkpoint> <checkpoint>Results filtered to relevant content only</checkpoint>
</stage> </stage>
<stage id="4" name="PersistToTemp"> <stage id="4" name="PersistToTemp" enforcement="MANDATORY">
<action>Save filtered documentation to .tmp/external-context/</action> <action>ALWAYS save filtered documentation to .tmp/external-context/ - NEVER skip this step</action>
<process> <process>
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` 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 ```markdown
--- ---
source: Context7 API source: Context7 API
@ -168,22 +179,32 @@ tags:
{filtered documentation content} {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
</process> </process>
<checkpoint>Documentation persisted to .tmp/external-context/</checkpoint> <checkpoint>Documentation persisted to .tmp/external-context/ AND files confirmed written</checkpoint>
</stage> </stage>
<stage id="5" name="ReturnLocations"> <stage id="5" name="ReturnLocations" enforcement="MANDATORY">
<action>Return file locations and brief summary</action> <action>Return file locations and brief summary ONLY AFTER files are written</action>
<output_format> <output_format>
CRITICAL: Only proceed to this stage AFTER Stage 4 is complete and files are written.
Return format:
``` ```
✅ Fetched: {library-name} ✅ 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} 📝 Summary: {1-2 line summary of what was fetched}
🔗 Official Docs: {link} 🔗 Official Docs: {link}
``` ```
⚠️ Do NOT say "ready to be persisted" - files must be ALREADY written
</output_format> </output_format>
<checkpoint>File locations returned, task complete</checkpoint> <checkpoint>File locations returned with confirmation files exist, task complete</checkpoint>
</stage> </stage>
</workflow_execution> </workflow_execution>
@ -214,18 +235,27 @@ If Context7 API fails:
- ❌ Don't use bash for anything except curl to context7.com - ❌ Don't use bash for anything except curl to context7.com
- ❌ Don't write outside `.tmp/external-context/` directory - ❌ Don't write outside `.tmp/external-context/` directory
- ❌ Don't use task tool—you're a fetcher with write-only persistence - ❌ 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 ## Success Criteria
You succeed when: You succeed when ALL of these are complete:
✅ Documentation is **fetched** from Context7 or official sources ✅ Documentation is **fetched** from Context7 or official sources
✅ Results are **filtered** to only relevant sections ✅ 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 ✅ **File locations returned** with brief summary
✅ **Official docs link** provided ✅ **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 ## References

View file

@ -13,9 +13,9 @@
| **Edit existing image** | This file | Image Specialist | tool:gemini | | **Edit existing image** | This file | Image Specialist | tool:gemini |
| **UI mockup (static)** | This file | Image Specialist | tool:gemini | | **UI mockup (static)** | This file | Image Specialist | tool:gemini |
| **Interactive UI design** | `workflows/design-iteration.md` | - | - | | **Interactive UI design** | `workflows/design-iteration.md` | - | - |
| **Design system** | `development/design-systems.md` | - | - | | **Design system** | `ui/web/design-systems.md` | - | - |
| **UI standards** | `development/ui-styling-standards.md` | - | - | | **UI standards** | `ui/web/ui-styling-standards.md` | - | - |
| **Animation patterns** | `development/animation-patterns.md` | - | - | | **Animation patterns** | `ui/web/animation-patterns.md` | - | - |
--- ---
@ -448,9 +448,9 @@ After receiving output:
## Related Context ## Related Context
- **UI Design Workflow**: `.opencode/context/core/workflows/design-iteration.md` - **UI Design Workflow**: `.opencode/context/core/workflows/design-iteration.md`
- **Design Systems**: `.opencode/context/development/design-systems.md` - **Design Systems**: `.opencode/context/ui/web/design-systems.md`
- **UI Styling Standards**: `.opencode/context/development/ui-styling-standards.md` - **UI Styling Standards**: `.opencode/context/ui/web/ui-styling-standards.md`
- **Animation Patterns**: `.opencode/context/development/animation-patterns.md` - **Animation Patterns**: `.opencode/context/ui/web/animation-patterns.md`
- **Subagent Invocation Guide**: `.opencode/context/openagents-repo/guides/subagent-invocation.md` - **Subagent Invocation Guide**: `.opencode/context/openagents-repo/guides/subagent-invocation.md`
- **Agent Capabilities**: `.opencode/context/openagents-repo/core-concepts/agents.md` - **Agent Capabilities**: `.opencode/context/openagents-repo/core-concepts/agents.md`

View file

@ -652,9 +652,9 @@ Before presenting each stage:
## References ## References
- [Design Systems Context](../development/design-systems.md) - [Design Systems Context](../ui/web/design-systems.md)
- [UI Styling Standards](../development/ui-styling-standards.md) - [UI Styling Standards](../ui/web/ui-styling-standards.md)
- [Animation Patterns](../development/animation-patterns.md) - [Animation Patterns](../ui/web/animation-patterns.md)
- [Design Assets](../development/design-assets.md) - [Design Assets](../ui/web/design-assets.md)
- [ASCII Art Generator](https://www.asciiart.eu/) - [ASCII Art Generator](https://www.asciiart.eu/)
- [WCAG Contrast Checker](https://webaim.org/resources/contrastchecker/) - [WCAG Contrast Checker](https://webaim.org/resources/contrastchecker/)

View file

@ -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.

View file

@ -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.

View file

@ -1,753 +0,0 @@
<!-- Context: development/animation-patterns | Priority: high | Version: 1.0 | Updated: 2025-12-09 -->
# 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)

View file

@ -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: <https://api.example.com/v2/users>; 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)

View file

@ -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

View file

@ -1,567 +0,0 @@
<!-- Context: development/design-assets | Priority: medium | Version: 1.0 | Updated: 2025-12-09 -->
# 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 (1200x800) -->
<img src="https://source.unsplash.com/random/1200x800" alt="Random image">
<!-- Random image with category -->
<img src="https://source.unsplash.com/random/1200x800/?nature" alt="Nature image">
<img src="https://source.unsplash.com/random/1200x800/?technology" alt="Technology image">
<img src="https://source.unsplash.com/random/1200x800/?people" alt="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
<!-- Use photo ID for consistency -->
<img src="https://images.unsplash.com/photo-1506905925346-21bda4d32df4" alt="Mountain landscape">
```
#### Placehold.co
**Simple Placeholders**:
```html
<!-- Basic placeholder (800x600) -->
<img src="https://placehold.co/800x600" alt="Placeholder">
<!-- With custom colors (background/text) -->
<img src="https://placehold.co/800x600/EEE/31343C" alt="Placeholder">
<!-- With text -->
<img src="https://placehold.co/800x600?text=Product+Image" alt="Product placeholder">
<!-- Different formats -->
<img src="https://placehold.co/800x600.png" alt="PNG placeholder">
<img src="https://placehold.co/800x600.jpg" alt="JPG placeholder">
<img src="https://placehold.co/800x600.webp" alt="WebP placeholder">
```
#### Picsum Photos
**Random Photos**:
```html
<!-- Random photo (800x600) -->
<img src="https://picsum.photos/800/600" alt="Random photo">
<!-- Specific photo by ID -->
<img src="https://picsum.photos/id/237/800/600" alt="Specific photo">
<!-- Grayscale -->
<img src="https://picsum.photos/800/600?grayscale" alt="Grayscale photo">
<!-- Blur effect -->
<img src="https://picsum.photos/800/600?blur=2" alt="Blurred photo">
```
### Image Best Practices
```html
<!-- Responsive image with srcset -->
<img
src="https://source.unsplash.com/random/800x600/?nature"
srcset="
https://source.unsplash.com/random/400x300/?nature 400w,
https://source.unsplash.com/random/800x600/?nature 800w,
https://source.unsplash.com/random/1200x900/?nature 1200w
"
sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
alt="Nature landscape"
loading="lazy"
>
<!-- Background image with object-fit -->
<div
class="w-full h-64 bg-cover bg-center rounded-lg"
style="background-image: url('https://source.unsplash.com/random/1200x800/?workspace')"
role="img"
aria-label="Workspace background"
></div>
<!-- Modern picture element -->
<picture>
<source
srcset="https://source.unsplash.com/random/1200x800/?nature"
media="(min-width: 1024px)"
>
<source
srcset="https://source.unsplash.com/random/800x600/?nature"
media="(min-width: 768px)"
>
<img
src="https://source.unsplash.com/random/400x300/?nature"
alt="Responsive nature image"
loading="lazy"
>
</picture>
```
---
## Icon Systems
### Lucide Icons (Recommended Default)
**Loading**:
```html
<!-- Load Lucide from CDN -->
<script src="https://unpkg.com/lucide@latest/dist/umd/lucide.min.js"></script>
<!-- Or specific version -->
<script src="https://unpkg.com/lucide@0.294.0/dist/umd/lucide.min.js"></script>
```
**Usage**:
```html
<!-- Icon elements -->
<i data-lucide="home"></i>
<i data-lucide="user"></i>
<i data-lucide="settings"></i>
<i data-lucide="search"></i>
<i data-lucide="menu"></i>
<i data-lucide="x"></i>
<i data-lucide="chevron-down"></i>
<i data-lucide="arrow-right"></i>
<!-- With custom size and color -->
<i data-lucide="heart" class="w-6 h-6 text-red-500"></i>
<!-- Initialize icons -->
<script>
lucide.createIcons();
</script>
```
**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
<!-- Heroicons via CDN (inline SVG) -->
<!-- Use individual icon imports or copy SVG code -->
```
**Usage**:
```html
<!-- Outline style (24x24) -->
<svg class="w-6 h-6" fill="none" stroke="currentColor" viewBox="0 0 24 24">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M3 12l2-2m0 0l7-7 7 7M5 10v10a1 1 0 001 1h3m10-11l2 2m-2-2v10a1 1 0 01-1 1h-3m-6 0a1 1 0 001-1v-4a1 1 0 011-1h2a1 1 0 011 1v4a1 1 0 001 1m-6 0h6" />
</svg>
<!-- Solid style (20x20) -->
<svg class="w-5 h-5" fill="currentColor" viewBox="0 0 20 20">
<path d="M10.707 2.293a1 1 0 00-1.414 0l-7 7a1 1 0 001.414 1.414L4 10.414V17a1 1 0 001 1h2a1 1 0 001-1v-2a1 1 0 011-1h2a1 1 0 011 1v2a1 1 0 001 1h2a1 1 0 001-1v-6.586l.293.293a1 1 0 001.414-1.414l-7-7z" />
</svg>
```
### Font Awesome
**Loading**:
```html
<!-- Font Awesome Free CDN -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.0/css/all.min.css">
```
**Usage**:
```html
<!-- Solid icons -->
<i class="fas fa-home"></i>
<i class="fas fa-user"></i>
<i class="fas fa-cog"></i>
<!-- Regular icons -->
<i class="far fa-heart"></i>
<i class="far fa-star"></i>
<!-- Brands -->
<i class="fab fa-github"></i>
<i class="fab fa-twitter"></i>
<i class="fab fa-linkedin"></i>
<!-- With sizing -->
<i class="fas fa-home fa-2x"></i>
<i class="fas fa-user fa-3x"></i>
```
### Icon Best Practices
```html
<!-- Always provide accessible labels -->
<button aria-label="Close menu">
<i data-lucide="x"></i>
</button>
<!-- Use semantic HTML with icons -->
<a href="#" class="flex items-center gap-2">
<i data-lucide="external-link" class="w-4 h-4"></i>
<span>Visit website</span>
</a>
<!-- Icon-only buttons need labels -->
<button aria-label="Search" class="p-2">
<i data-lucide="search" class="w-5 h-5"></i>
</button>
<!-- Decorative icons should be hidden from screen readers -->
<div>
<i data-lucide="star" aria-hidden="true"></i>
<span>Featured</span>
</div>
```
---
## Font Loading
### Google Fonts (Recommended)
**Loading**:
```html
<!-- Preconnect for performance -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<!-- Load font families -->
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
<!-- Multiple fonts -->
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600&display=swap" rel="stylesheet">
```
**Usage**:
```css
body {
font-family: 'Inter', sans-serif;
}
code, pre {
font-family: 'JetBrains Mono', monospace;
}
```
**Popular Font Combinations**:
```html
<!-- Modern UI: Inter + JetBrains Mono -->
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
<!-- Professional: Roboto + Roboto Mono -->
<link href="https://fonts.googleapis.com/css2?family=Roboto:wght@400;500;700&family=Roboto+Mono:wght@400;500&display=swap" rel="stylesheet">
<!-- Editorial: Playfair Display + Source Sans Pro -->
<link href="https://fonts.googleapis.com/css2?family=Playfair+Display:wght@400;700&family=Source+Sans+Pro:wght@400;600&display=swap" rel="stylesheet">
<!-- Friendly: Poppins + Space Mono -->
<link href="https://fonts.googleapis.com/css2?family=Poppins:wght@400;500;600;700&family=Space+Mono:wght@400;700&display=swap" rel="stylesheet">
```
### Font Loading Strategies
```html
<!-- Optimal loading with font-display -->
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600&display=swap" rel="stylesheet">
<!-- Preload critical fonts -->
<link rel="preload" href="/fonts/inter-var.woff2" as="font" type="font/woff2" crossorigin>
<!-- Self-hosted fonts -->
<style>
@font-face {
font-family: 'Inter';
src: url('/fonts/inter-var.woff2') format('woff2');
font-weight: 100 900;
font-display: swap;
}
</style>
```
---
## CDN Resources
### CSS Frameworks
```html
<!-- Tailwind CSS -->
<script src="https://cdn.tailwindcss.com"></script>
<!-- Flowbite -->
<link href="https://cdn.jsdelivr.net/npm/flowbite@2.0.0/dist/flowbite.min.css" rel="stylesheet">
<script src="https://cdn.jsdelivr.net/npm/flowbite@2.0.0/dist/flowbite.min.js"></script>
<!-- Bootstrap -->
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js"></script>
```
### JavaScript Libraries
```html
<!-- Alpine.js -->
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3.x.x/dist/cdn.min.js"></script>
<!-- HTMX -->
<script src="https://unpkg.com/htmx.org@1.9.10"></script>
<!-- Chart.js -->
<script src="https://cdn.jsdelivr.net/npm/chart.js@4.4.0/dist/chart.umd.min.js"></script>
```
### Utility Libraries
```html
<!-- Animate.css -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/animate.css/4.1.1/animate.min.css">
<!-- AOS (Animate On Scroll) -->
<link href="https://unpkg.com/aos@2.3.1/dist/aos.css" rel="stylesheet">
<script src="https://unpkg.com/aos@2.3.1/dist/aos.js"></script>
```
---
## SVG Assets
### Inline SVG
```html
<!-- Custom icon -->
<svg class="w-6 h-6" viewBox="0 0 24 24" fill="none" stroke="currentColor">
<path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 4v16m8-8H4" />
</svg>
<!-- Logo -->
<svg class="h-8 w-auto" viewBox="0 0 100 40" fill="currentColor">
<path d="M10 10h80v20H10z" />
</svg>
```
### SVG Backgrounds
```html
<!-- Pattern background -->
<div class="w-full h-64" style="background-image: url('data:image/svg+xml,<svg xmlns=&quot;http://www.w3.org/2000/svg&quot; viewBox=&quot;0 0 80 80&quot;><path fill=&quot;%23f0f0f0&quot; d=&quot;M0 0h80v80H0z&quot;/><path fill=&quot;%23e0e0e0&quot; d=&quot;M0 0h40v40H0zm40 40h40v40H40z&quot;/></svg>')"></div>
```
---
## Video Assets
### Placeholder Videos
```html
<!-- Sample video from CDN -->
<video class="w-full rounded-lg" controls>
<source src="https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4" type="video/mp4">
Your browser does not support the video tag.
</video>
<!-- Background video -->
<video class="w-full h-screen object-cover" autoplay muted loop playsinline>
<source src="https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/ForBiggerBlazes.mp4" type="video/mp4">
</video>
```
---
## 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
<!-- Lazy loading -->
<img src="image.jpg" loading="lazy" alt="Description">
<!-- Modern formats with fallback -->
<picture>
<source srcset="image.webp" type="image/webp">
<source srcset="image.jpg" type="image/jpeg">
<img src="image.jpg" alt="Description">
</picture>
<!-- Responsive images -->
<img
srcset="image-400.jpg 400w, image-800.jpg 800w, image-1200.jpg 1200w"
sizes="(max-width: 768px) 100vw, 50vw"
src="image-800.jpg"
alt="Description"
>
```
### Font Optimization
```html
<!-- Subset fonts (only load needed characters) -->
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;600&text=ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789&display=swap" rel="stylesheet">
<!-- Preload critical fonts -->
<link rel="preload" href="/fonts/inter.woff2" as="font" type="font/woff2" crossorigin>
```
### CDN Best Practices
```html
<!-- Use integrity hashes for security -->
<script
src="https://cdn.jsdelivr.net/npm/alpinejs@3.13.3/dist/cdn.min.js"
integrity="sha384-..."
crossorigin="anonymous"
></script>
<!-- Specify versions to avoid breaking changes -->
<script src="https://unpkg.com/lucide@0.294.0/dist/umd/lucide.min.js"></script>
```
---
## 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
<!-- Informative image -->
<img src="chart.png" alt="Sales increased 25% in Q4 2024">
<!-- Decorative image -->
<img src="decoration.png" alt="" role="presentation">
<!-- Complex image with description -->
<figure>
<img src="diagram.png" alt="System architecture diagram">
<figcaption>
The diagram shows three layers: frontend, API, and database.
</figcaption>
</figure>
```
### Icon Accessibility
```html
<!-- Icon with visible text -->
<button class="flex items-center gap-2">
<i data-lucide="trash" aria-hidden="true"></i>
<span>Delete</span>
</button>
<!-- Icon-only button -->
<button aria-label="Delete item">
<i data-lucide="trash"></i>
</button>
<!-- Icon with screen reader text -->
<button>
<i data-lucide="search" aria-hidden="true"></i>
<span class="sr-only">Search</span>
</button>
```
---
## 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)

View file

@ -1,381 +0,0 @@
<!-- Context: development/design-systems | Priority: high | Version: 1.0 | Updated: 2025-12-09 -->
# 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
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
```
---
## 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)

View file

@ -2,41 +2,34 @@
**Purpose**: Client-side development patterns **Purpose**: Client-side development patterns
**Status**: 🚧 Placeholder - Content coming soon
--- ---
## Planned Structure ## Structure
``` ```
frontend/ frontend/
├── navigation.md ├── navigation.md
│ ├── when-to-delegate.md
├── react/ └── 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/
├── navigation.md ├── navigation.md
├── context-patterns.md └── react-patterns.md
├── zustand-patterns.md
└── redux-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
--- ---

View file

@ -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`

View file

@ -0,0 +1,468 @@
<!-- Context: development/frontend/when-to-delegate | Priority: high | Version: 1.0 | Updated: 2026-01-30 -->
# 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`

View file

@ -26,11 +26,12 @@ development/
│ ├── navigation.md │ ├── navigation.md
│ └── mastra-ai/ │ └── mastra-ai/
│ │
├── frontend/ # Client-side (future) ├── frontend/ # Client-side
│ ├── navigation.md │ ├── navigation.md
│ ├── react/ │ ├── when-to-delegate.md # When to use frontend-specialist
│ ├── vue/ │ └── react/
│ └── state-management/ │ ├── navigation.md
│ └── react-patterns.md
│ │
├── backend/ # Server-side (future) ├── backend/ # Server-side (future)
│ ├── navigation.md │ ├── navigation.md
@ -64,6 +65,7 @@ development/
| Task | Path | | Task | Path |
|------|------| |------|------|
| **UI/Frontend** | `ui-navigation.md` | | **UI/Frontend** | `ui-navigation.md` |
| **When to delegate frontend** | `frontend/when-to-delegate.md` |
| **Backend/API** | `backend-navigation.md` | | **Backend/API** | `backend-navigation.md` |
| **Full-stack** | `fullstack-navigation.md` | | **Full-stack** | `fullstack-navigation.md` |
| **Clean code** | `principles/clean-code.md` | | **Clean code** | `principles/clean-code.md` |
@ -76,7 +78,7 @@ development/
**Principles** → Universal development practices **Principles** → Universal development practices
**Frameworks** → Full-stack frameworks (Tanstack Start, Next.js) **Frameworks** → Full-stack frameworks (Tanstack Start, Next.js)
**AI** → AI frameworks and agent runtimes (MAStra AI) **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) **Backend** → APIs, Node.js, Python, auth (future)
**Data** → SQL, NoSQL, ORMs (future) **Data** → SQL, NoSQL, ORMs (future)
**Integration** → Packages, APIs, services (future) **Integration** → Packages, APIs, services (future)

View file

@ -8,13 +8,9 @@
``` ```
Frontend Code (development/frontend/): Frontend Code (development/frontend/):
├── react/ # [future] └── react/
│ ├── hooks-patterns.md ├── navigation.md
│ ├── component-architecture.md └── react-patterns.md
│ └── tanstack/
│ ├── query-patterns.md
│ └── router-patterns.md
└── vue/ # [future]
Visual Design (ui/web/): Visual Design (ui/web/):
├── animation-patterns.md ├── animation-patterns.md
@ -31,8 +27,7 @@ Visual Design (ui/web/):
| Task | Path | | Task | Path |
|------|------| |------|------|
| **React patterns** | `frontend/react/hooks-patterns.md` [future] | | **React patterns** | `frontend/react/react-patterns.md` |
| **TanStack Query** | `frontend/react/tanstack/query-patterns.md` [future] |
| **Animations** | `../../ui/web/animation-patterns.md` | | **Animations** | `../../ui/web/animation-patterns.md` |
| **Styling** | `../../ui/web/ui-styling-standards.md` | | **Styling** | `../../ui/web/ui-styling-standards.md` |
| **Design systems** | `../../ui/web/design-systems.md` | | **Design systems** | `../../ui/web/design-systems.md` |
@ -41,13 +36,11 @@ Visual Design (ui/web/):
## By Framework ## By Framework
**React** → `frontend/react/` [future] **React** → `frontend/react/`
**Vue** → `frontend/vue/` [future]
**TanStack** → `frontend/react/tanstack/` [future]
## By Concern ## By Concern
**Code patterns** → `development/frontend/` [future] **Code patterns** → `development/frontend/`
**Visual design** → `ui/web/` **Visual design** → `ui/web/`
--- ---

View file

@ -1,552 +0,0 @@
<!-- Context: development/ui-styling-standards | Priority: high | Version: 1.0 | Updated: 2025-12-09 -->
# 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
<!-- ✅ Use CDN script tag -->
<script src="https://cdn.tailwindcss.com"></script>
```
**Avoid**:
```html
<!-- ❌ Don't use stylesheet link -->
<link href="https://cdn.jsdelivr.net/npm/tailwindcss@2.2.19/dist/tailwind.min.css" rel="stylesheet">
```
**Why**: Script tag allows for JIT compilation and configuration
### Flowbite
**Loading Method**:
```html
<!-- Flowbite CSS -->
<link href="https://cdn.jsdelivr.net/npm/flowbite@2.0.0/dist/flowbite.min.css" rel="stylesheet">
<!-- Flowbite JS -->
<script src="https://cdn.jsdelivr.net/npm/flowbite@2.0.0/dist/flowbite.min.js"></script>
```
**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
<!-- Mobile: stack, Desktop: side-by-side -->
<div class="flex flex-col md:flex-row">
<div class="w-full md:w-1/2">Left</div>
<div class="w-full md:w-1/2">Right</div>
</div>
<!-- Mobile: full width, Desktop: constrained -->
<div class="w-full lg:w-3/4 xl:w-1/2 mx-auto">
Content
</div>
```
### 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 on dark background -->
<div class="bg-gray-900 p-8">
<div class="bg-white text-gray-900 p-6 rounded-lg">
Light card content
</div>
</div>
<!-- Dark card on light background -->
<div class="bg-gray-50 p-8">
<div class="bg-gray-900 text-white p-6 rounded-lg">
Dark card content
</div>
</div>
```
### 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 */
<div class="m-4 p-4 flex">
```
### 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
<!-- Horizontal layout -->
<div class="flex items-center gap-4">
<div>Item 1</div>
<div>Item 2</div>
</div>
<!-- Vertical layout -->
<div class="flex flex-col gap-4">
<div>Item 1</div>
<div>Item 2</div>
</div>
<!-- Centered content -->
<div class="flex items-center justify-center min-h-screen">
<div>Centered content</div>
</div>
```
### Grid (Preferred for 2D layouts)
```html
<!-- Responsive grid -->
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
<div>Card 1</div>
<div>Card 2</div>
<div>Card 3</div>
</div>
<!-- Dashboard layout -->
<div class="grid grid-cols-12 gap-4">
<aside class="col-span-12 lg:col-span-3">Sidebar</aside>
<main class="col-span-12 lg:col-span-9">Content</main>
</div>
```
### Container Patterns
```html
<!-- Centered container with max width -->
<div class="container mx-auto px-4 max-w-7xl">
Content
</div>
<!-- Full-width section with contained content -->
<section class="w-full bg-gray-50">
<div class="container mx-auto px-4 py-12 max-w-6xl">
Content
</div>
</section>
```
---
## Typography Standards
### Hierarchy
```html
<!-- Heading scale -->
<h1 class="text-4xl md:text-5xl lg:text-6xl font-bold">Main Heading</h1>
<h2 class="text-3xl md:text-4xl font-semibold">Section Heading</h2>
<h3 class="text-2xl md:text-3xl font-semibold">Subsection</h3>
<h4 class="text-xl md:text-2xl font-medium">Minor Heading</h4>
<!-- Body text -->
<p class="text-base md:text-lg leading-relaxed">Body text</p>
<p class="text-sm text-gray-600">Secondary text</p>
<p class="text-xs text-gray-500">Caption text</p>
```
### Font Loading
**Always use Google Fonts**:
```html
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
```
**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
<!-- Primary button -->
<button class="bg-primary text-primary-foreground px-6 py-3 rounded-lg font-medium hover:opacity-90 transition-opacity">
Primary Action
</button>
<!-- Secondary button -->
<button class="bg-secondary text-secondary-foreground px-6 py-3 rounded-lg font-medium hover:bg-secondary/80 transition-colors">
Secondary Action
</button>
<!-- Outline button -->
<button class="border-2 border-primary text-primary px-6 py-3 rounded-lg font-medium hover:bg-primary hover:text-primary-foreground transition-all">
Outline Action
</button>
```
### Cards
```html
<!-- Basic card -->
<div class="bg-card text-card-foreground rounded-lg shadow-md p-6">
<h3 class="text-xl font-semibold mb-2">Card Title</h3>
<p class="text-muted-foreground">Card content</p>
</div>
<!-- Interactive card -->
<div class="bg-card text-card-foreground rounded-lg shadow-md p-6 hover:shadow-lg transition-shadow cursor-pointer">
<h3 class="text-xl font-semibold mb-2">Interactive Card</h3>
<p class="text-muted-foreground">Hover for effect</p>
</div>
```
### Forms
```html
<!-- Input field -->
<div class="space-y-2">
<label class="block text-sm font-medium">Email</label>
<input
type="email"
class="w-full px-4 py-2 border border-input rounded-lg focus:ring-2 focus:ring-ring focus:border-transparent transition-all"
placeholder="you@example.com"
>
</div>
<!-- Textarea -->
<div class="space-y-2">
<label class="block text-sm font-medium">Message</label>
<textarea
class="w-full px-4 py-2 border border-input rounded-lg focus:ring-2 focus:ring-ring focus:border-transparent transition-all resize-none"
rows="4"
placeholder="Your message..."
></textarea>
</div>
```
---
## Accessibility Standards
### ARIA Labels
```html
<!-- Button with icon -->
<button aria-label="Close dialog">
<svg>...</svg>
</button>
<!-- Navigation -->
<nav aria-label="Main navigation">
<ul>...</ul>
</nav>
```
### Semantic HTML
```html
<!-- ✅ Use semantic elements -->
<header>...</header>
<nav>...</nav>
<main>...</main>
<article>...</article>
<aside>...</aside>
<footer>...</footer>
<!-- ❌ Avoid div soup -->
<div class="header">...</div>
<div class="nav">...</div>
<div class="main">...</div>
```
### Focus States
```css
/* Always provide visible focus states */
button:focus-visible {
outline: 2px solid var(--ring);
outline-offset: 2px;
}
/* Tailwind utility */
<button class="focus:ring-2 focus:ring-ring focus:ring-offset-2">
Button
</button>
```
---
## Performance Optimization
### CSS Loading
```html
<!-- Preconnect to font sources -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<!-- Preload critical fonts -->
<link rel="preload" href="/fonts/inter.woff2" as="font" type="font/woff2" crossorigin>
```
### Image Optimization
```html
<!-- Responsive images -->
<img
src="image-800.jpg"
srcset="image-400.jpg 400w, image-800.jpg 800w, image-1200.jpg 1200w"
sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
alt="Description"
loading="lazy"
>
```
### Critical CSS
```html
<!-- Inline critical CSS -->
<style>
/* Above-the-fold styles */
body { margin: 0; font-family: system-ui; }
.hero { min-height: 100vh; }
</style>
<!-- Load full CSS async -->
<link rel="stylesheet" href="styles.css" media="print" onload="this.media='all'">
```
---
## 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
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">
<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js"></script>
```
**Bulma**:
```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bulma@0.9.4/css/bulma.min.css">
```
**Foundation**:
```html
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/foundation-sites@6.7.5/dist/css/foundation.min.css">
<script src="https://cdn.jsdelivr.net/npm/foundation-sites@6.7.5/dist/js/foundation.min.js"></script>
```
---
## 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)

View file

@ -210,7 +210,7 @@ evals/framework/src/types/ # TypeScript types
**Examples**: **Examples**:
- `.opencode/context/core/standards/code-quality.md` - `.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` - `.opencode/context/content-creation/principles/copywriting-frameworks.md`
### Tests ### Tests

View file

@ -30,10 +30,10 @@
"context:core/*", "context:core/*",
"context:project-intelligence/*", "context:project-intelligence/*",
"context:to-be-consumed/*", "context:to-be-consumed/*",
"context:development/ui-styling-standards", "context:ui/web/ui-styling-standards",
"context:development/design-systems", "context:ui/web/design-systems",
"context:development/design-assets", "context:ui/web/design-assets",
"context:development/animation-patterns", "context:ui/web/animation-patterns",
"config:env-example", "config:env-example",
"config:readme", "config:readme",
"skill:context-manager", "skill:context-manager",

View file

@ -2118,76 +2118,6 @@
"dependencies": [], "dependencies": [],
"category": "standard" "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", "id": "mastra-config",
"name": "Mastra Config", "name": "Mastra Config",
@ -2615,18 +2545,6 @@
], ],
"category": "standard" "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", "id": "learning-readme",
"name": "Learning README", "name": "Learning README",
@ -2663,19 +2581,6 @@
], ],
"category": "standard" "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", "id": "context-bundle-template",
"name": "Context Bundle Template", "name": "Context Bundle Template",
@ -2773,7 +2678,7 @@
}, },
"developer": { "developer": {
"name": "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", "badge": "RECOMMENDED",
"components": [ "components": [
"agent:openagent", "agent:openagent",
@ -2803,6 +2708,15 @@
"context:project-intelligence/*", "context:project-intelligence/*",
"context:to-be-consumed/*", "context:to-be-consumed/*",
"context:adding-skill", "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:env-example",
"config:readme" "config:readme"
] ]
@ -2839,7 +2753,7 @@
}, },
"full": { "full": {
"name": "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": [ "components": [
"agent:openagent", "agent:openagent",
"agent:opencoder", "agent:opencoder",
@ -2877,13 +2791,22 @@
"context:project-intelligence/*", "context:project-intelligence/*",
"context:to-be-consumed/*", "context:to-be-consumed/*",
"context:adding-skill", "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:env-example",
"config:readme" "config:readme"
] ]
}, },
"advanced": { "advanced": {
"name": "Advanced (Meta-Level)", "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": [ "components": [
"agent:openagent", "agent:openagent",
"agent:opencoder", "agent:opencoder",
@ -2930,6 +2853,25 @@
"context:project-intelligence/*", "context:project-intelligence/*",
"context:to-be-consumed/*", "context:to-be-consumed/*",
"context:adding-skill", "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:env-example",
"config:readme" "config:readme"
], ],