cclohmar/OpenWriterControle
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
OpenWriterControle/.opencode/context/development/design-systems.md
Darren Hinde c8f7103cb6
refactor(evals): consolidate documentation and enhance test infrastructure (#56) 
* feat(agents): implement category-based agent organization system

- Organize agents into domain categories (core, development, content, data, product, learning)
- Move 10 agents to category subdirectories with proper git rename tracking
- Update 13 subagents with category and type metadata in frontmatter
- Add category metadata files (0-category.json) documenting common patterns
- Implement local registry fallback in install script for offline development
- Add comprehensive validation suite with 15 automated tests (100% pass rate)
- Enhance registry validation with duplicate ID and consistency checks
- Update eval framework with intelligent path resolution (backward compatible)
- Archive legacy eval structure to _archive/ for reference
- Update all documentation to reflect category-based structure
- Bump version to 0.5.0 with accurate CHANGELOG

Technical Details:
- 23 agents organized (10 category agents, 13 subagents)
- 6 category directories created
- Path resolution supports both agent IDs and category paths
- Registry schema updated to v2.0.0
- 159 files changed, 872 insertions(+), 10738 deletions(-)

BREAKING CHANGE: Agent file paths now use category structure. Update references from .opencode/agent/openagent.md to .opencode/agent/core/openagent.md. Eval framework maintains backward compatibility via path resolution.

* refactor(evals): consolidate documentation and enhance test infrastructure

- Remove temporary project tracking files (PHASE_5_COMPLETE, PROJECT_COMPLETE, etc.)
- Consolidate evaluation framework docs into main README
- Enhance test execution with improved logging and multi-prompt support
- Move system-builder from core to meta category
- Add comprehensive test suites for openagent with organized structure
- Create evaluation test structure for all subagents
- Clean up archived workflows and redundant documentation
- Update registry to reflect new agent organization
- Add shared test templates and golden test patterns

* feat(ci): add manual trigger support for bot-created PRs in validate-registry workflow

- Add pr_number input to workflow_dispatch for manually triggering validation
- Fetch PR details dynamically when triggered manually
- Support both automatic (PR event) and manual (workflow_dispatch) triggers
- Enable validation of bot-created PRs like automated version bumps
- Update branch detection and push logic to handle both trigger types
- Add documentation explaining how to manually trigger for bot PRs

* feat(evals): add explicit context file validation to test framework

- Add expectedContextFiles field to test YAML schema for explicit context file specification
- Enhance context-loading-evaluator to support both auto-detect and explicit validation modes
- Update documentation with comprehensive guide and examples
- Clean up archived legacy test structure (90+ old test files)
- Add new example tests demonstrating explicit context validation
- Backward compatible with existing tests

* feat(evals): add multi-agent logging system and performance optimizations

Implement comprehensive multi-agent logging and performance improvements for the eval framework.

Task 01: Multi-Agent Logging System
- Add complete hierarchical logging module (evals/framework/src/logging/)
  - SessionTracker: tracks parent-child delegation hierarchies
  - MultiAgentLogger: pretty-prints logs with visual indentation
  - Formatters: box characters and emoji formatting
  - 37 passing unit tests (session-tracker, logger, integration)
- Integrate with SDK event stream handler
  - Hook into session.created, message.updated, message.part.updated events
  - Real-time child session detection via timestamp heuristics
  - Message deduplication for cleaner output
- Enable in debug mode only (<1% performance overhead)
- Add demo script and comprehensive documentation

Task 02: Performance Optimizations
- Reduce grace period from 5s to 2s (67% reduction, 10-20% faster tests)
- Add PerformanceMetricsEvaluator for bottleneck identification
  - Collects tool latencies, inference time, idle time
  - Provides full performance visibility
- Update smoke test to validate delegation (core feature)
  - Replace simple read test with multi-agent delegation test
  - Tests both parent and child agent functionality
  - Validates multi-agent logging system

Results:
- 37 unit tests passing
- Smoke test passing (95/100 score)
- Clean hierarchical logging output
- 10-20% faster test execution
- Full multi-agent visibility

Files changed: 16 files, +2678 lines
Time saved: ~6-8 days (completed in 6 hours vs 3-5 day estimate)

* feat(evals): show child agent execution in non-debug mode

- Enable MultiAgentLogger in both debug and non-debug modes
- Add verbose parameter to control output level
- Non-verbose mode shows concise child session lifecycle:
  - Child agent started message
  - Child agent completed with duration
- Verbose mode (--debug) shows full delegation hierarchy
- Update documentation to reflect new behavior

This provides visibility into delegation without overwhelming output,
giving confidence that child agents are actually running.

* feat(evals): improve delegation testing and behavior validation

Major improvements to eval framework:

Test Suite:
- Add 00-smoke-test.yaml (basic read operation)
- Rename 01-smoke-test.yaml → 02-delegation-test.yaml (delegation test)
- Add simple-responder test agent for delegation testing
- Add debug test: simple-subagent-call.yaml

Evaluators:
- Add agent-model-evaluator.ts for agent/model validation
- Enhance behavior-evaluator.ts with detailed task tool output
- Improve delegation-evaluator.ts with better evidence tracking

Schema & Execution:
- Add expectedAgent and expectedModel to test schema
- Improve test executor with better logging and error handling

Documentation:
- Update evals/README.md with new features and performance improvements
- Remove outdated MULTI_AGENT_LOGGING_COMPLETE.md

Registry:
- Add simple-responder test agent to registry

Fixes:
- Fix dashboard.sh path resolution

These changes provide better visibility into delegation, improved test
coverage, and clearer validation of agent behavior.

* chore: add GitHub Actions workflow and plugin documentation

- Add .github/workflows/evals/run-evaluations.yml for automated eval testing
- Add dev/ai-tools/opencode/plugins/Plugin-inspiration.md for plugin development reference
2025-12-18 09:52:11 +00:00

10 KiB
Raw Blame History

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:

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

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

<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):

box-shadow: 0 1px 3px 0px hsl(0 0% 0% / 0.10);

Hard Shadows (Neo-brutalism):

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

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