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
GitHub
parent
38995b24c8
commit
7472575aaa
20 changed files with 615 additions and 3070 deletions
|
|
@ -81,9 +81,16 @@ tags:
|
|||
NEVER rely on training data for library APIs
|
||||
</rule>
|
||||
<rule id="output_format">
|
||||
ALWAYS write files to .tmp/external-context/ BEFORE returning summary
|
||||
ALWAYS return: file locations + brief summary + official docs link
|
||||
ALWAYS filter to relevant sections only
|
||||
NO reports, guides, or integration documentation
|
||||
NEVER say "ready to be persisted" - files must be WRITTEN, not just fetched
|
||||
</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>
|
||||
</critical_rules>
|
||||
|
||||
|
|
@ -93,19 +100,21 @@ tags:
|
|||
<tier level="1" desc="Critical Operations">
|
||||
- @tool_usage: Use ONLY allowed tools
|
||||
- @always_use_tools: Fetch from real sources
|
||||
- @output_format: Return file locations + brief summary
|
||||
- @mandatory_persistence: ALWAYS write files to .tmp/external-context/ (Stage 4 is MANDATORY)
|
||||
- @output_format: Return file locations + brief summary ONLY AFTER files written
|
||||
</tier>
|
||||
<tier level="2" desc="Core Workflow">
|
||||
- Detect library from registry
|
||||
- Fetch from Context7 (primary)
|
||||
- Fallback to official docs (webfetch)
|
||||
- Filter to relevant sections
|
||||
- Persist to .tmp/external-context/
|
||||
- Persist to .tmp/external-context/ (CANNOT be skipped)
|
||||
- Return file locations + summary
|
||||
</tier>
|
||||
<conflict_resolution>
|
||||
Tier 1 always overrides Tier 2
|
||||
If workflow conflicts w/ tool restrictions→abort and report error
|
||||
Stage 4 (PersistToTemp) is MANDATORY and cannot be skipped under any circumstances
|
||||
</conflict_resolution>
|
||||
</execution_priority>
|
||||
|
||||
|
|
@ -150,12 +159,14 @@ tags:
|
|||
<checkpoint>Results filtered to relevant content only</checkpoint>
|
||||
</stage>
|
||||
|
||||
<stage id="4" name="PersistToTemp">
|
||||
<action>Save filtered documentation to .tmp/external-context/</action>
|
||||
<stage id="4" name="PersistToTemp" enforcement="MANDATORY">
|
||||
<action>ALWAYS save filtered documentation to .tmp/external-context/ - NEVER skip this step</action>
|
||||
<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`
|
||||
3. Write file with minimal metadata header:
|
||||
3. Write file using Write tool with minimal metadata header:
|
||||
```markdown
|
||||
---
|
||||
source: Context7 API
|
||||
|
|
@ -168,22 +179,32 @@ tags:
|
|||
|
||||
{filtered documentation content}
|
||||
```
|
||||
4. Update `.tmp/external-context/.manifest.json` with file metadata
|
||||
4. Confirm file written by checking it exists
|
||||
5. Update `.tmp/external-context/.manifest.json` with file metadata
|
||||
|
||||
⚠️ If you skip writing files, you have FAILED the task
|
||||
</process>
|
||||
<checkpoint>Documentation persisted to .tmp/external-context/</checkpoint>
|
||||
<checkpoint>Documentation persisted to .tmp/external-context/ AND files confirmed written</checkpoint>
|
||||
</stage>
|
||||
|
||||
<stage id="5" name="ReturnLocations">
|
||||
<action>Return file locations and brief summary</action>
|
||||
<stage id="5" name="ReturnLocations" enforcement="MANDATORY">
|
||||
<action>Return file locations and brief summary ONLY AFTER files are written</action>
|
||||
<output_format>
|
||||
CRITICAL: Only proceed to this stage AFTER Stage 4 is complete and files are written.
|
||||
|
||||
Return format:
|
||||
```
|
||||
✅ Fetched: {library-name}
|
||||
📁 Saved to: .tmp/external-context/{package-name}/{topic}.md
|
||||
📁 Files written to:
|
||||
- .tmp/external-context/{package-name}/{topic-1}.md
|
||||
- .tmp/external-context/{package-name}/{topic-2}.md
|
||||
📝 Summary: {1-2 line summary of what was fetched}
|
||||
🔗 Official Docs: {link}
|
||||
```
|
||||
|
||||
⚠️ Do NOT say "ready to be persisted" - files must be ALREADY written
|
||||
</output_format>
|
||||
<checkpoint>File locations returned, task complete</checkpoint>
|
||||
<checkpoint>File locations returned with confirmation files exist, task complete</checkpoint>
|
||||
</stage>
|
||||
</workflow_execution>
|
||||
|
||||
|
|
@ -214,18 +235,27 @@ If Context7 API fails:
|
|||
- ❌ Don't use bash for anything except curl to context7.com
|
||||
- ❌ Don't write outside `.tmp/external-context/` directory
|
||||
- ❌ Don't use task tool—you're a fetcher with write-only persistence
|
||||
- ❌ **NEVER skip writing files** - fetching without persisting = FAILURE
|
||||
- ❌ **NEVER say "ready to be persisted"** - files must be WRITTEN before returning
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
You succeed when:
|
||||
You succeed when ALL of these are complete:
|
||||
✅ Documentation is **fetched** from Context7 or official sources
|
||||
✅ Results are **filtered** to only relevant sections
|
||||
✅ Documentation is **persisted** to `.tmp/external-context/{package-name}/{topic}.md`
|
||||
✅ Files are **WRITTEN** to `.tmp/external-context/{package-name}/{topic}.md` using Write tool
|
||||
✅ Files are **CONFIRMED** to exist (not just "ready to be persisted")
|
||||
✅ **File locations returned** with brief summary
|
||||
✅ **Official docs link** provided
|
||||
|
||||
❌ You FAIL if you:
|
||||
- Fetch docs but don't write files
|
||||
- Say "ready to be persisted" without actually writing
|
||||
- Skip Stage 4 (PersistToTemp)
|
||||
- Return summary without file locations
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
|
|
|||
|
|
@ -13,9 +13,9 @@
|
|||
| **Edit existing image** | This file | Image Specialist | tool:gemini |
|
||||
| **UI mockup (static)** | This file | Image Specialist | tool:gemini |
|
||||
| **Interactive UI design** | `workflows/design-iteration.md` | - | - |
|
||||
| **Design system** | `development/design-systems.md` | - | - |
|
||||
| **UI standards** | `development/ui-styling-standards.md` | - | - |
|
||||
| **Animation patterns** | `development/animation-patterns.md` | - | - |
|
||||
| **Design system** | `ui/web/design-systems.md` | - | - |
|
||||
| **UI standards** | `ui/web/ui-styling-standards.md` | - | - |
|
||||
| **Animation patterns** | `ui/web/animation-patterns.md` | - | - |
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -448,9 +448,9 @@ After receiving output:
|
|||
## Related Context
|
||||
|
||||
- **UI Design Workflow**: `.opencode/context/core/workflows/design-iteration.md`
|
||||
- **Design Systems**: `.opencode/context/development/design-systems.md`
|
||||
- **UI Styling Standards**: `.opencode/context/development/ui-styling-standards.md`
|
||||
- **Animation Patterns**: `.opencode/context/development/animation-patterns.md`
|
||||
- **Design Systems**: `.opencode/context/ui/web/design-systems.md`
|
||||
- **UI Styling Standards**: `.opencode/context/ui/web/ui-styling-standards.md`
|
||||
- **Animation Patterns**: `.opencode/context/ui/web/animation-patterns.md`
|
||||
- **Subagent Invocation Guide**: `.opencode/context/openagents-repo/guides/subagent-invocation.md`
|
||||
- **Agent Capabilities**: `.opencode/context/openagents-repo/core-concepts/agents.md`
|
||||
|
||||
|
|
|
|||
|
|
@ -652,9 +652,9 @@ Before presenting each stage:
|
|||
|
||||
## References
|
||||
|
||||
- [Design Systems Context](../development/design-systems.md)
|
||||
- [UI Styling Standards](../development/ui-styling-standards.md)
|
||||
- [Animation Patterns](../development/animation-patterns.md)
|
||||
- [Design Assets](../development/design-assets.md)
|
||||
- [Design Systems Context](../ui/web/design-systems.md)
|
||||
- [UI Styling Standards](../ui/web/ui-styling-standards.md)
|
||||
- [Animation Patterns](../ui/web/animation-patterns.md)
|
||||
- [Design Assets](../ui/web/design-assets.md)
|
||||
- [ASCII Art Generator](https://www.asciiart.eu/)
|
||||
- [WCAG Contrast Checker](https://webaim.org/resources/contrastchecker/)
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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)
|
||||
|
|
@ -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)
|
||||
|
|
@ -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
|
||||
|
|
@ -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="http://www.w3.org/2000/svg" viewBox="0 0 80 80"><path fill="%23f0f0f0" d="M0 0h80v80H0z"/><path fill="%23e0e0e0" d="M0 0h40v40H0zm40 40h40v40H40z"/></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)
|
||||
|
|
@ -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)
|
||||
|
|
@ -2,41 +2,34 @@
|
|||
|
||||
**Purpose**: Client-side development patterns
|
||||
|
||||
**Status**: 🚧 Placeholder - Content coming soon
|
||||
|
||||
---
|
||||
|
||||
## Planned Structure
|
||||
## Structure
|
||||
|
||||
```
|
||||
frontend/
|
||||
├── navigation.md
|
||||
│
|
||||
├── react/
|
||||
│ ├── navigation.md
|
||||
│ ├── hooks-patterns.md
|
||||
│ ├── component-architecture.md
|
||||
│ ├── performance.md
|
||||
│ └── tanstack/
|
||||
│ ├── query-patterns.md
|
||||
│ ├── router-patterns.md
|
||||
│ └── table-patterns.md
|
||||
│
|
||||
├── vue/
|
||||
│ └── navigation.md
|
||||
│
|
||||
└── state-management/
|
||||
├── when-to-delegate.md
|
||||
└── react/
|
||||
├── navigation.md
|
||||
├── context-patterns.md
|
||||
├── zustand-patterns.md
|
||||
└── redux-patterns.md
|
||||
└── react-patterns.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## For Now
|
||||
## Quick Routes
|
||||
|
||||
Use specialized navigation: `../ui-navigation.md`
|
||||
| Task | Path |
|
||||
|------|------|
|
||||
| **When to delegate** | `when-to-delegate.md` |
|
||||
| **React patterns** | `react/react-patterns.md` |
|
||||
| **React navigation** | `react/navigation.md` |
|
||||
|
||||
---
|
||||
|
||||
## By Framework
|
||||
|
||||
**React** → `react/` - Modern React patterns, hooks, component design
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
19
.opencode/context/development/frontend/react/navigation.md
Normal file
19
.opencode/context/development/frontend/react/navigation.md
Normal 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`
|
||||
468
.opencode/context/development/frontend/when-to-delegate.md
Normal file
468
.opencode/context/development/frontend/when-to-delegate.md
Normal 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`
|
||||
|
|
@ -26,11 +26,12 @@ development/
|
|||
│ ├── navigation.md
|
||||
│ └── mastra-ai/
|
||||
│
|
||||
├── frontend/ # Client-side (future)
|
||||
├── frontend/ # Client-side
|
||||
│ ├── navigation.md
|
||||
│ ├── react/
|
||||
│ ├── vue/
|
||||
│ └── state-management/
|
||||
│ ├── when-to-delegate.md # When to use frontend-specialist
|
||||
│ └── react/
|
||||
│ ├── navigation.md
|
||||
│ └── react-patterns.md
|
||||
│
|
||||
├── backend/ # Server-side (future)
|
||||
│ ├── navigation.md
|
||||
|
|
@ -64,6 +65,7 @@ development/
|
|||
| Task | Path |
|
||||
|------|------|
|
||||
| **UI/Frontend** | `ui-navigation.md` |
|
||||
| **When to delegate frontend** | `frontend/when-to-delegate.md` |
|
||||
| **Backend/API** | `backend-navigation.md` |
|
||||
| **Full-stack** | `fullstack-navigation.md` |
|
||||
| **Clean code** | `principles/clean-code.md` |
|
||||
|
|
@ -76,7 +78,7 @@ development/
|
|||
**Principles** → Universal development practices
|
||||
**Frameworks** → Full-stack frameworks (Tanstack Start, Next.js)
|
||||
**AI** → AI frameworks and agent runtimes (MAStra AI)
|
||||
**Frontend** → React, Vue, state management (future)
|
||||
**Frontend** → React patterns and component design
|
||||
**Backend** → APIs, Node.js, Python, auth (future)
|
||||
**Data** → SQL, NoSQL, ORMs (future)
|
||||
**Integration** → Packages, APIs, services (future)
|
||||
|
|
|
|||
|
|
@ -8,13 +8,9 @@
|
|||
|
||||
```
|
||||
Frontend Code (development/frontend/):
|
||||
├── react/ # [future]
|
||||
│ ├── hooks-patterns.md
|
||||
│ ├── component-architecture.md
|
||||
│ └── tanstack/
|
||||
│ ├── query-patterns.md
|
||||
│ └── router-patterns.md
|
||||
└── vue/ # [future]
|
||||
└── react/
|
||||
├── navigation.md
|
||||
└── react-patterns.md
|
||||
|
||||
Visual Design (ui/web/):
|
||||
├── animation-patterns.md
|
||||
|
|
@ -31,8 +27,7 @@ Visual Design (ui/web/):
|
|||
|
||||
| Task | Path |
|
||||
|------|------|
|
||||
| **React patterns** | `frontend/react/hooks-patterns.md` [future] |
|
||||
| **TanStack Query** | `frontend/react/tanstack/query-patterns.md` [future] |
|
||||
| **React patterns** | `frontend/react/react-patterns.md` |
|
||||
| **Animations** | `../../ui/web/animation-patterns.md` |
|
||||
| **Styling** | `../../ui/web/ui-styling-standards.md` |
|
||||
| **Design systems** | `../../ui/web/design-systems.md` |
|
||||
|
|
@ -41,13 +36,11 @@ Visual Design (ui/web/):
|
|||
|
||||
## By Framework
|
||||
|
||||
**React** → `frontend/react/` [future]
|
||||
**Vue** → `frontend/vue/` [future]
|
||||
**TanStack** → `frontend/react/tanstack/` [future]
|
||||
**React** → `frontend/react/`
|
||||
|
||||
## By Concern
|
||||
|
||||
**Code patterns** → `development/frontend/` [future]
|
||||
**Code patterns** → `development/frontend/`
|
||||
**Visual design** → `ui/web/`
|
||||
|
||||
---
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
@ -210,7 +210,7 @@ evals/framework/src/types/ # TypeScript types
|
|||
|
||||
**Examples**:
|
||||
- `.opencode/context/core/standards/code-quality.md`
|
||||
- `.opencode/context/development/react-patterns.md`
|
||||
- `.opencode/context/development/frontend/react/react-patterns.md`
|
||||
- `.opencode/context/content-creation/principles/copywriting-frameworks.md`
|
||||
|
||||
### Tests
|
||||
|
|
|
|||
|
|
@ -30,10 +30,10 @@
|
|||
"context:core/*",
|
||||
"context:project-intelligence/*",
|
||||
"context:to-be-consumed/*",
|
||||
"context:development/ui-styling-standards",
|
||||
"context:development/design-systems",
|
||||
"context:development/design-assets",
|
||||
"context:development/animation-patterns",
|
||||
"context:ui/web/ui-styling-standards",
|
||||
"context:ui/web/design-systems",
|
||||
"context:ui/web/design-assets",
|
||||
"context:ui/web/animation-patterns",
|
||||
"config:env-example",
|
||||
"config:readme",
|
||||
"skill:context-manager",
|
||||
|
|
|
|||
138
registry.json
138
registry.json
|
|
@ -2118,76 +2118,6 @@
|
|||
"dependencies": [],
|
||||
"category": "standard"
|
||||
},
|
||||
{
|
||||
"id": "design-assets",
|
||||
"name": "Design Assets",
|
||||
"type": "context",
|
||||
"path": ".opencode/context/development/design-assets.md",
|
||||
"description": "Design Assets",
|
||||
"tags": [],
|
||||
"dependencies": [],
|
||||
"category": "standard"
|
||||
},
|
||||
{
|
||||
"id": "ui-styling-standards",
|
||||
"name": "Ui Styling Standards",
|
||||
"type": "context",
|
||||
"path": ".opencode/context/development/ui-styling-standards.md",
|
||||
"description": "UI Styling Standards",
|
||||
"tags": [],
|
||||
"dependencies": [],
|
||||
"category": "standard"
|
||||
},
|
||||
{
|
||||
"id": "clean-code",
|
||||
"name": "Clean Code",
|
||||
"type": "context",
|
||||
"path": ".opencode/context/development/clean-code.md",
|
||||
"description": "Clean Code Principles",
|
||||
"tags": [],
|
||||
"dependencies": [],
|
||||
"category": "standard"
|
||||
},
|
||||
{
|
||||
"id": "animation-patterns",
|
||||
"name": "Animation Patterns",
|
||||
"type": "context",
|
||||
"path": ".opencode/context/development/animation-patterns.md",
|
||||
"description": "Animation Patterns",
|
||||
"tags": [],
|
||||
"dependencies": [],
|
||||
"category": "standard"
|
||||
},
|
||||
{
|
||||
"id": "design-systems",
|
||||
"name": "Design Systems",
|
||||
"type": "context",
|
||||
"path": ".opencode/context/development/design-systems.md",
|
||||
"description": "Design Systems",
|
||||
"tags": [],
|
||||
"dependencies": [],
|
||||
"category": "standard"
|
||||
},
|
||||
{
|
||||
"id": "react-patterns",
|
||||
"name": "React Patterns",
|
||||
"type": "context",
|
||||
"path": ".opencode/context/development/react-patterns.md",
|
||||
"description": "React Patterns & Best Practices",
|
||||
"tags": [],
|
||||
"dependencies": [],
|
||||
"category": "standard"
|
||||
},
|
||||
{
|
||||
"id": "api-design",
|
||||
"name": "Api Design",
|
||||
"type": "context",
|
||||
"path": ".opencode/context/development/api-design.md",
|
||||
"description": "API Design Patterns",
|
||||
"tags": [],
|
||||
"dependencies": [],
|
||||
"category": "standard"
|
||||
},
|
||||
{
|
||||
"id": "mastra-config",
|
||||
"name": "Mastra Config",
|
||||
|
|
@ -2615,18 +2545,6 @@
|
|||
],
|
||||
"category": "standard"
|
||||
},
|
||||
{
|
||||
"id": "development-readme",
|
||||
"name": "Development README",
|
||||
"type": "context",
|
||||
"path": ".opencode/context/development/README.md",
|
||||
"description": "Development context overview and guide",
|
||||
"tags": [
|
||||
"development",
|
||||
"guide"
|
||||
],
|
||||
"category": "standard"
|
||||
},
|
||||
{
|
||||
"id": "learning-readme",
|
||||
"name": "Learning README",
|
||||
|
|
@ -2663,19 +2581,6 @@
|
|||
],
|
||||
"category": "standard"
|
||||
},
|
||||
{
|
||||
"id": "mastra-ai-readme",
|
||||
"name": "Mastra AI README",
|
||||
"type": "context",
|
||||
"path": ".opencode/context/development/ai/mastra-ai/README.md",
|
||||
"description": "Mastra AI framework documentation and guides",
|
||||
"tags": [
|
||||
"mastra-ai",
|
||||
"ai",
|
||||
"development"
|
||||
],
|
||||
"category": "standard"
|
||||
},
|
||||
{
|
||||
"id": "context-bundle-template",
|
||||
"name": "Context Bundle Template",
|
||||
|
|
@ -2773,7 +2678,7 @@
|
|||
},
|
||||
"developer": {
|
||||
"name": "Developer",
|
||||
"description": "Complete software development environment with code generation, testing, review, and build tools. Use OpenAgent for general tasks (1-4 files) or OpenCoder for complex architecture (4+ files). Recommended for most developers.",
|
||||
"description": "Complete software development environment with code generation, testing, review, and build tools. Includes UI/UX patterns, development principles, and design systems. Use OpenAgent for general tasks (1-4 files) or OpenCoder for complex architecture (4+ files). Recommended for most developers.",
|
||||
"badge": "RECOMMENDED",
|
||||
"components": [
|
||||
"agent:openagent",
|
||||
|
|
@ -2803,6 +2708,15 @@
|
|||
"context:project-intelligence/*",
|
||||
"context:to-be-consumed/*",
|
||||
"context:adding-skill",
|
||||
"context:ui/*",
|
||||
"context:development/*",
|
||||
"context:design-systems",
|
||||
"context:react-patterns",
|
||||
"context:animation-patterns",
|
||||
"context:ui-styling-standards",
|
||||
"context:design-assets",
|
||||
"context:clean-code",
|
||||
"context:api-design",
|
||||
"config:env-example",
|
||||
"config:readme"
|
||||
]
|
||||
|
|
@ -2839,7 +2753,7 @@
|
|||
},
|
||||
"full": {
|
||||
"name": "Full",
|
||||
"description": "Everything included - all agents, subagents, tools, and plugins for maximum functionality.",
|
||||
"description": "Everything included - all agents, subagents, tools, and plugins for maximum functionality. Includes UI/UX patterns, development principles, and design systems.",
|
||||
"components": [
|
||||
"agent:openagent",
|
||||
"agent:opencoder",
|
||||
|
|
@ -2877,13 +2791,22 @@
|
|||
"context:project-intelligence/*",
|
||||
"context:to-be-consumed/*",
|
||||
"context:adding-skill",
|
||||
"context:ui/*",
|
||||
"context:development/*",
|
||||
"context:design-systems",
|
||||
"context:react-patterns",
|
||||
"context:animation-patterns",
|
||||
"context:ui-styling-standards",
|
||||
"context:design-assets",
|
||||
"context:clean-code",
|
||||
"context:api-design",
|
||||
"config:env-example",
|
||||
"config:readme"
|
||||
]
|
||||
},
|
||||
"advanced": {
|
||||
"name": "Advanced (Meta-Level)",
|
||||
"description": "Full installation plus System Builder for creating custom AI architectures. For power users and contributors.",
|
||||
"description": "Full installation plus System Builder for creating custom AI architectures. Includes comprehensive context system, system builder templates, and repository management tools. For power users and contributors.",
|
||||
"components": [
|
||||
"agent:openagent",
|
||||
"agent:opencoder",
|
||||
|
|
@ -2930,6 +2853,25 @@
|
|||
"context:project-intelligence/*",
|
||||
"context:to-be-consumed/*",
|
||||
"context:adding-skill",
|
||||
"context:ui/*",
|
||||
"context:development/*",
|
||||
"context:design-systems",
|
||||
"context:react-patterns",
|
||||
"context:animation-patterns",
|
||||
"context:ui-styling-standards",
|
||||
"context:design-assets",
|
||||
"context:clean-code",
|
||||
"context:api-design",
|
||||
"context:system-builder-guide",
|
||||
"context:orchestrator-template",
|
||||
"context:subagent-template",
|
||||
"context:openagents-repo/*",
|
||||
"context:context-system",
|
||||
"context:context-system/*",
|
||||
"context:registry-dependencies",
|
||||
"context:templates",
|
||||
"context:frontmatter",
|
||||
"context:codebase-references",
|
||||
"config:env-example",
|
||||
"config:readme"
|
||||
],
|
||||
|
|
|
|||
Loading…
Reference in a new issue