Skip to main content

OSSA Design Guide

Complete design system for building consistent OSSA pages

Brand guidelines, components, colors, typography, and patterns

Brand Identity

Logo

OSSA Logo

The OSSA logo represents the hub-and-spoke architecture of agent orchestration. The central hub (primary blue) connects to agent nodes (secondary cyan).

Usage: Always maintain clear space around the logo (minimum 20% of logo height)

Minimum size: 40px × 40px for digital use

Do not: Rotate, distort, or recolor the logo

Tagline

"The OpenAPI for AI Agents"

This tagline should appear prominently on the homepage and in key marketing materials. It communicates OSSA's purpose: standardizing agent definitions just as OpenAPI standardized REST APIs.

Usage: Homepage hero, marketing pages, documentation headers

Variations: Can be shortened to "The OpenAPI for Agents" in tight spaces

Color System

Primary Brand Colors

Primary

Primary Blue-Purple

Hex: #4A3ECD

RGB: 74, 62, 205

Represents the OSSA hub/standard. Use for primary actions, links, and key UI elements.

Secondary

Secondary Cyan-Blue

Hex: #1CB9ED

RGB: 28, 185, 237

Represents agent nodes. Use for secondary actions, accents, and complementary elements.

Gradient

Brand Gradient

From: #4A3ECD

To: #1CB9ED

Use for hero sections, backgrounds, and prominent visual elements.

Semantic Colors

Success

#10b981 (muted)

Use: bg-success or text-success

Warning

#f59e0b (muted)

Use: bg-warning or text-warning

Error

#ef4444 (muted)

Use: bg-error or text-error

Info

#06b6d4 (muted)

Use: bg-info or text-info

Color Usage Guidelines

  • Primary (#4A3ECD): Main CTAs, links, headings, borders for primary sections
  • Secondary (#1CB9ED): Secondary CTAs, accents, complementary borders, highlights
  • Accent (#9060EA): Purple accent for highlights and special elements
  • Gradients: Hero sections, card backgrounds (use subtle opacity: /10, /20, /30)
  • Neutral Grays: Body text (gray-700), borders (gray-300), backgrounds (gray-50, gray-100)
  • Semantic Colors: Use muted semantic colors (success, warning, error, info) for status indicators. All defined in styles/_variables.scss.
  • Centralized System: All colors are defined in styles/_variables.scss as SCSS variables. Update colors in ONE place! The SCSS variables are compiled to CSS variables and exposed via Tailwind classes.
  • Usage: Use bg-success, bg-warning, bg-error, bg-info for backgrounds, or with opacity like bg-success/20
  • Update Colors: Edit styles/_variables.scss to change any color. Restart dev server after changes.
  • Avoid: Random color assignments. Use brand colors or semantic colors with purpose.

♿ Accessibility Guidelines

Contrast Ratios (WCAG AA)

  • • Primary on White: 7.4:1 (AAA ✓)
  • • Secondary on White: 3.1:1 (AA Large ✓)
  • • Gray-700 on White: 4.6:1 (AA ✓)
  • • White on Primary: 7.4:1 (AAA ✓)

Best Practices

  • • Always test color combinations for sufficient contrast
  • • Avoid using color alone to convey information
  • • Include text labels with icon-only buttons
  • • Use focus indicators (ring-2 ring-primary) on interactive elements

Typography

Font Families

Body & Headings

Inter, system-ui, -apple-system, sans-serif

Used for all body text, headings, and UI elements. Clean, modern, highly readable.

Code & Monospace

JetBrains Mono, Menlo, Monaco, Courier New, monospace

Used for code blocks, inline code, and technical content.

Type Scale

Heading 1

text-5xl (3rem) - Hero titles

Heading 2

text-3xl (1.875rem) - Section titles

Heading 3

text-2xl (1.5rem) - Subsection titles

Heading 4

text-xl (1.25rem) - Card titles

Body Text

text-base (1rem) - Default body

Small Text

text-sm (0.875rem) - Captions, metadata

Design Tokens

Spacing Scale

gap-14px
gap-28px
gap-416px
gap-624px
gap-832px
gap-1248px
gap-1664px

Shadow System

shadow-sm

Subtle shadow for cards

shadow-md

Default shadow for elevated elements

shadow-lg

Prominent shadow for modals

shadow-xl

Maximum depth for overlays

Animation Timings

duration-150150ms - Fast (hovers, clicks)
duration-300300ms - Normal (transitions)
duration-500500ms - Slow (modals, slides)

Example: transition-all duration-300 ease-in-out

Responsive Breakpoints

sm:640px - Small tablets
md:768px - Tablets
lg:1024px - Desktops
xl:1280px - Large desktops

Example: grid md:grid-cols-2 lg:grid-cols-3

Components

Buttons

Usage: Primary buttons for main actions, secondary for alternative actions, outline for less prominent actions. Always use brand colors (primary/secondary) or semantic colors (success/warning/error).

Cards

Standard Card

Default card style

Highlighted Card

For important content

Interactive Card

With hover effect

Usage: Use standard cards for content sections. Use highlighted cards for featured/important content. Use colored left borders (border-l-4) to indicate category or importance.

Hero Sections

Hero Section Title

Hero section description text

Usage: All major pages should start with a hero section using the brand gradient. Include an icon badge, title, and descriptive text. Use white text on gradient backgrounds.

Accordions

Accordion content goes here. Use for collapsible sections with related content.

Usage: Use accordions for organizing long-form content. Alternate between primary and secondary border colors. First item should be open by default.

Form Elements

Usage: All form elements use border-2 and focus:ring-2 for accessibility. Always include labels and use focus:border-primary for visual feedback.

Navigation Patterns

Horizontal Navigation

Usage: Use horizontal navigation for top-level pages and vertical navigation for sidebars. Always include icons with vertical navigation items for visual hierarchy.

Layout Patterns

Page Structure

1. Hero Section

Gradient background, icon, title, description

2. Content Sections

Cards, grids, accordions, content blocks

3. Call-to-Action

Links to Agent Builder, examples, docs

Section Headers

Section Title

All major sections should have an icon badge (gradient background) and colored heading. Use primary color for main sections, secondary for subsections.

Best Practices

Do

  • • Use brand colors (primary/secondary) consistently
  • • Start pages with gradient hero sections
  • • Use cards for content organization
  • • Include icon badges with section headers
  • • Use accordions for long-form content
  • • Maintain consistent spacing (gap-4, gap-6, gap-8)
  • • Use semantic colors for status indicators
  • • Keep text readable (gray-700 for body, gray-900 for headings)

Don't

  • • Use random colors without purpose
  • • Mix too many colors in one section
  • • Use emojis in component titles (icons only)
  • • Create pages without hero sections
  • • Use inconsistent spacing
  • • Overuse gradients (use subtle opacity)
  • • Use colors that clash with brand colors
  • • Make text too small (minimum text-base for body)

Code Examples

Hero Section Template

<div className="bg-gradient-to-br from-primary via-accent to-secondary text-white py-16 px-4">
  <div className="container mx-auto max-w-6xl text-center">
    <div className="inline-flex items-center justify-center w-20 h-20 bg-white/20 backdrop-blur-sm rounded-full mb-6">
      <svg className="w-10 h-10" fill="none" stroke="currentColor" viewBox="0 0 24 24">
        {/* Icon */}
      </svg>
    </div>
    <h1 className="text-5xl font-bold mb-4">Page Title</h1>
    <p className="text-xl text-white/90 mb-2">Description</p>
  </div>
</div>

Future Roadmap: studio-ui Integration

The studio-ui component library is under development and will be integrated in a future update. This library provides advanced, production-ready components built with accessibility and performance in mind.

# Install the package
npm i @bluefly/studio-ui
# Configure GitLab registry
echo @bluefly:registry=https://gitlab.com/api/v4/packages/npm/ >> .npmrc

Repository: gitlab.com/blueflyio/agent-platform/studio-ui

Planned Components for Integration

Design System

  • • Liquid Glass Theme: Advanced glassmorphism design system
  • • Design Tokens: Centralized color, spacing, typography tokens
  • • Theme API: Dynamic theming with runtime customization
  • • Component Variants: Pre-built component variations

🧩 UI Components

  • • Forms: Advanced form components with validation
  • • Charts: Data visualization components
  • • Navigation: Complex navigation patterns
  • • Layouts: Responsive layout components

Agent-Specific Components

  • • Agent Dashboard: Real-time agent monitoring
  • • Compliance Viewers: Policy and compliance displays
  • • Registry UI: Agent registry management interface
  • • Workflow Builders: Visual workflow composition

Infrastructure Components

  • • Deployment Tools: CI/CD and deployment interfaces
  • • Metrics Displays: Infrastructure metrics visualization
  • • Feature Toggles: Feature management UI
  • • Infrastructure Dashboard: System health monitoring

⏰ Integration Timeline

This version (v0.4.1) focuses on DRY refactoring and core design system documentation. The studio-ui integration is planned for a future major update (v0.5.0 or later).

Next Steps: Complete v0.4.1 deployment → Review studio-ui component maturity → Plan migration strategy → Integrate in phases

Additional Resources

Component Files

  • • components/layout/Header.tsx
  • • components/layout/Footer.tsx
  • • components/Logo.tsx

Reference Pages