Web Interface Styling Guide

Web Interface Styling Guide {#web-styling-guide}¶

Back to Home

This guide establishes the design system and styling conventions for the ByteBiota web interface. Following these guidelines ensures visual consistency, maintainability, and a cohesive user experience across all pages.

Design Philosophy¶

The ByteBiota web interface follows a modern, scientific aesthetic that balances functionality with visual appeal. The design emphasizes:

Clarity: Clean, uncluttered layouts that prioritize information hierarchy
Consistency: Unified visual language across all components and pages
Accessibility: High contrast, readable typography, and keyboard navigation
Responsiveness: Seamless experience across desktop, tablet, and mobile devices
Scientific Precision: Professional appearance suitable for research and analysis

Color System¶

Primary Colors¶

--digital-blue: #1e40af;      /* Primary brand color */
--evolution-green: #059669;   /* Success states, positive metrics */
--warning-orange: #ea580c;    /* Warnings, caution states */
--error-red: #dc2626;         /* Errors, critical states */

Neutral Colors (Light Mode)¶

--bg-primary: #f8fafc;        /* Main background */
--bg-secondary: #ffffff;      /* Card backgrounds */
--bg-tertiary: #f1f5f9;       /* Subtle backgrounds */
--border-color: #e2e8f0;      /* Borders and dividers */
--text-primary: #0f172a;      /* Primary text */
--text-secondary: #64748b;    /* Secondary text */
--text-muted: #94a3b8;        /* Muted text */

Neutral Colors (Dark Mode)¶

--bg-primary: #0f172a;        /* Main background */
--bg-secondary: #1e293b;      /* Card backgrounds */
--bg-tertiary: #334155;       /* Subtle backgrounds */
--border-color: #334155;      /* Borders and dividers */
--text-primary: #f1f5f9;      /* Primary text */
--text-secondary: #94a3b8;    /* Secondary text */
--text-muted: #64748b;        /* Muted text */

Accent Colors¶

--purple: #7c3aed;            /* Special highlights */
--cyan: #0891b2;              /* Data visualization */
--pink: #db2777;              /* Interactive elements */

Typography¶

Font Stack¶

--font-family: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;

Font Sizes¶

--font-size-xs: 0.75rem;      /* 12px - Small labels */
--font-size-sm: 0.875rem;     /* 14px - Body text */
--font-size-base: 1rem;       /* 16px - Default text */
--font-size-lg: 1.125rem;     /* 18px - Large text */
--font-size-xl: 1.25rem;      /* 20px - Small headings */
--font-size-2xl: 1.5rem;      /* 24px - Medium headings */
--font-size-3xl: 2rem;        /* 32px - Large headings */
--font-size-4xl: 2.5rem;      /* 40px - Hero headings */

Font Weights¶

400 (Normal): Body text, descriptions
500 (Medium): Labels, secondary headings
600 (Semibold): Primary headings, important text
700 (Bold): Hero text, emphasis

Spacing System¶

Spacing Scale¶

--spacing-xs: 0.25rem;        /* 4px */
--spacing-sm: 0.5rem;         /* 8px */
--spacing-md: 1rem;           /* 16px */
--spacing-lg: 1.5rem;         /* 24px */
--spacing-xl: 2rem;           /* 32px */
--spacing-2xl: 3rem;          /* 48px */
--spacing-3xl: 4rem;          /* 64px */

Usage Guidelines¶

xs: Tight spacing between related elements
sm: Small gaps between form elements
md: Standard spacing between sections
lg: Larger gaps between major sections
xl: Page-level spacing
2xl/3xl: Hero sections, major dividers

Border Radius¶

--radius-sm: 0.375rem;        /* 6px - Small elements */
--radius-md: 0.5rem;          /* 8px - Buttons, inputs */
--radius-lg: 0.75rem;         /* 12px - Cards, containers */
--radius-xl: 1rem;            /* 16px - Large containers */

Shadows¶

--shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.05);     /* Subtle elevation */
--shadow-md: 0 4px 6px rgba(0, 0, 0, 0.1);      /* Card elevation */
--shadow-lg: 0 10px 15px rgba(0, 0, 0, 0.1);    /* Modal elevation */

Transitions¶

--transition-fast: 0.15s ease;    /* Hover effects */
--transition-normal: 0.3s ease;   /* Standard animations */
--transition-slow: 0.5s ease;     /* Complex animations */

Layout Patterns¶

Page Structure¶

Every page should follow this consistent structure:

<div class="page-container">
    <!-- Header Section -->
    <div class="page-header">
        <h1 class="page-title">Page Title</h1>
        <div class="header-controls">
            <!-- Controls, filters, actions -->
        </div>
    </div>

    <!-- KPI Cards Section -->
    <div class="kpi-section">
        <div class="kpi-grid">
            <!-- KPI cards -->
        </div>
    </div>

    <!-- Main Content Sections -->
    <div class="content-section">
        <div class="section-header">
            <h2 class="section-title">Section Title</h2>
        </div>
        <div class="section-content">
            <!-- Section content -->
        </div>
    </div>
</div>

Container Classes¶

.page-container: Main page wrapper with max-width and padding
.page-header: Header section with title and controls
.kpi-section: KPI cards container
.content-section: Main content sections
.section-header: Section title and controls
.section-content: Section body content

Component Patterns¶

KPI Cards¶

<div class="kpi-card">
    <div class="kpi-icon">📊</div>
    <div class="kpi-content">
        <h3 class="kpi-value">1,234</h3>
        <p class="kpi-label">Total Organisms</p>
    </div>
</div>

Styling:
- Background: var(--bg-secondary)
- Border: 1px solid var(--border-color)
- Border radius: var(--radius-lg)
- Padding: 20px
- Hover: translateY(-2px) with enhanced shadow

Section Headers¶

<div class="section-header">
    <h2 class="section-title">📈 Charts</h2>
    <div class="section-controls">
        <!-- Optional controls -->
    </div>
</div>

Styling:
- Font size: var(--font-size-2xl)
- Font weight: 600
- Color: var(--text-primary)
- Margin bottom: 20px

Cards¶

<div class="card">
    <div class="card-header">
        <h3 class="card-title">Card Title</h3>
        <div class="card-controls">
            <!-- Optional controls -->
        </div>
    </div>
    <div class="card-content">
        <!-- Card content -->
    </div>
</div>

Styling:
- Background: var(--bg-secondary)
- Border: 1px solid var(--border-color)
- Border radius: var(--radius-lg)
- Box shadow: var(--shadow-sm)
- Header: Gradient background with white text

Buttons¶

<button class="btn btn-primary">Primary Action</button>
<button class="btn btn-secondary">Secondary Action</button>
<button class="btn btn-success">Success Action</button>
<button class="btn btn-warning">Warning Action</button>
<button class="btn btn-danger">Danger Action</button>

Styling:
- Border radius: var(--radius-md)
- Padding: 12px 20px
- Font weight: 500
- Transition: var(--transition-fast)
- Hover: translateY(-1px) with shadow

Tables¶

<div class="table-container">
    <table class="table">
        <thead>
            <tr>
                <th>Column Header</th>
            </tr>
        </thead>
        <tbody>
            <tr>
                <td>Data Cell</td>
            </tr>
        </tbody>
    </table>
</div>

Styling:
- Container: var(--bg-secondary) background with border
- Headers: var(--bg-tertiary) background
- Borders: var(--border-color)
- Hover: var(--bg-tertiary) background on rows

Modals¶

<div class="modal-overlay" id="modalId" style="display: none;">
    <div class="modal">
        <div class="modal-header">
            <h3 class="modal-title">Modal Title</h3>
            <button class="modal-close" onclick="closeModal()">×</button>
        </div>
        <div class="modal-body">
            <!-- Modal content -->
        </div>
    </div>
</div>

Styling:
- Overlay: rgba(0, 0, 0, 0.7) with backdrop blur
- Modal: var(--bg-secondary) background
- Border radius: var(--radius-lg)
- Box shadow: var(--shadow-lg)
- Animation: Slide-in from top with scale

Chart Containers¶

Standard Chart Container¶

<div class="chart-container">
    <div class="chart-header">
        <h3>Chart Title</h3>
        <div class="chart-controls">
            <button class="chart-btn" onclick="toggleFullscreen()">⛶</button>
        </div>
    </div>
    <div class="chart-wrapper">
        <canvas id="chartId"></canvas>
    </div>
</div>

Styling:
- Container: var(--bg-secondary) background
- Header: Gradient background with white text
- Wrapper: 300px height with padding
- Controls: Semi-transparent white buttons

Responsive Design¶

Breakpoints¶

/* Mobile */
@media (max-width: 480px) { }

/* Tablet */
@media (max-width: 768px) { }

/* Desktop */
@media (min-width: 769px) { }

Responsive Patterns¶

Grid layouts: Use grid-template-columns: repeat(auto-fit, minmax(Xpx, 1fr))
Flexible containers: Use flex-wrap for button groups
Stack on mobile: Single column layouts for small screens
Touch targets: Minimum 44px for interactive elements

Animation Guidelines¶

Hover Effects¶

Cards: translateY(-2px) with enhanced shadow
Buttons: translateY(-1px) with shadow
Links: Color transition only

Loading States¶

Spinners: Use consistent spin animation
Skeletons: Subtle pulsing animation
Transitions: var(--transition-fast) for most interactions

Page Transitions¶

Fade in: opacity: 0 to opacity: 1
Slide in: translateY(10px) to translateY(0)
Scale in: scale(0.95) to scale(1)

Accessibility¶

Color Contrast¶

Text: Minimum 4.5:1 contrast ratio
UI elements: Minimum 3:1 contrast ratio
Focus states: High contrast outlines

Tab order: Logical flow through interactive elements
Focus indicators: Visible focus rings
Skip links: For main content areas

Screen Readers¶

Semantic HTML: Use proper heading hierarchy
ARIA labels: For complex interactions
Alt text: For all images and icons

Implementation Checklist¶

When creating a new page or component:

✅ Structure¶

[ ] Use consistent page layout pattern
[ ] Include proper section headers
[ ] Follow semantic HTML structure

✅ Styling¶

[ ] Use CSS custom properties for colors/spacing
[ ] Apply consistent border radius and shadows
[ ] Include hover and focus states

✅ Responsive¶

[ ] Test on mobile, tablet, and desktop
[ ] Use flexible grid layouts
[ ] Ensure touch targets are adequate

✅ Accessibility¶

[ ] Check color contrast ratios
[ ] Test keyboard navigation
[ ] Verify screen reader compatibility

✅ Performance¶

[ ] Use efficient CSS selectors
[ ] Minimize layout thrashing
[ ] Optimize animations for 60fps

File Organization¶

CSS Structure¶

src/bytebiota/ui/static/css/
├── main.css              # Base styles, CSS variables
├── components.css        # Reusable component styles
├── [page].css           # Page-specific styles
└── charts.css           # Chart-specific styles

Naming Conventions¶

CSS Classes: Use kebab-case (.kpi-card, .section-header)
CSS Variables: Use kebab-case with -- prefix (--bg-primary)
IDs: Use camelCase for JavaScript hooks (#workerModal)

Best Practices¶

Do's¶

✅ Use CSS custom properties for all colors and spacing
✅ Follow the established component patterns
✅ Test across all supported browsers
✅ Include proper error states and loading indicators
✅ Use semantic HTML elements
✅ Implement proper focus management

Don'ts¶

❌ Don't use hardcoded colors or spacing values
❌ Don't create one-off component styles
❌ Don't ignore responsive design requirements
❌ Don't skip accessibility considerations
❌ Don't use inline styles (except for dynamic values)
❌ Don't mix different design patterns on the same page

Brand Elements {#brand-elements}¶

Logo Design {#logo-design}¶

Style: Modern, geometric, representing digital evolution
Colors: Digital Blue primary, Evolution Green accent
Usage: Always maintain aspect ratio, minimum size 32px

Favicon {#favicon}¶

Design: Simplified version of logo
Sizes: 16x16, 32x32, 48x48, 192x192
Format: ICO and PNG

Loading Animation {#loading-animation}¶

Concept: DNA helix or digital organism evolution
Duration: 2-3 seconds
Colors: Brand colors with subtle animation

Maintenance¶

Regular Reviews¶

Monthly: Review new components for consistency
Quarterly: Update color palette and spacing if needed
Annually: Comprehensive design system audit

Documentation Updates¶

Update this guide when adding new patterns
Document any deviations with rationale
Keep examples current with actual implementation

This styling guide ensures that the ByteBiota web interface maintains a professional, consistent appearance while remaining flexible enough to accommodate new features and pages. Following these guidelines will result in a cohesive user experience that reflects the scientific precision and modern design philosophy of the ByteBiota platform.