Brand and UI Kit¶

This document defines the ConnectSoft brand system and UI kit, serving as the single source of truth for visual style. It is written for designers, frontend developers, and documentation maintainers creating ConnectSoft-branded materials, interfaces, and documentation.

The brand system balances technical professionalism with subtle warmth—serious engineering meets intelligent automation. This kit provides implementation-ready tokens, components, and guidance for MkDocs, Figma, and SaaS UIs (Blazor/React).

Important

Single Source of Truth: This document is authoritative for all ConnectSoft visual and UI language. All public-facing assets must conform to this brand system or have a documented exception.

Brand Overview and Principles¶

Visual Identity¶

ConnectSoft should feel visually:

Modern - Contemporary, forward-thinking, not dated
Confident - Professional, trustworthy, enterprise-grade
Technical - Built for developers and architects who value precision
AI-Powered - Intelligent, autonomous, agentic
Calm and Readable - Not flashy or "startup-y neon"

Design Principles¶

Clear Hierarchy - Visual hierarchy guides users through content
Low Visual Noise - Minimal decoration, focus on content
Structure Emphasis - Grids, alignment, consistent spacing
High Contrast - Accessibility-first, WCAG AA minimum
Neutral Backgrounds - Prefer neutral backgrounds with accent colors for emphasis
Consistent Patterns - Reusable components and patterns

Important

Non-Negotiables: 1. No Random Colors - Use only colors from the defined palette 2. Avoid Heavy Effects - No heavy shadows, gradients, or "toy" looks 3. Consistent Diagrams - Keep diagrams and tables consistent with brand 4. Typography Scale - Follow the defined typography scale, not arbitrary sizes

See: Domains & Branding Overview for domain brand relationships.

Color System¶

Palette Overview¶

The color system uses token-based naming with conceptual names and hex values. Colors are chosen for accessibility (WCAG AA minimum) and work across light and dark themes.

Token Name	Role	Example Hex	Usage
`color-primary`	Main brand accent	`#2563EB`	Links, main CTAs, highlights
`color-primary-soft`	Light variant for backgrounds	`#DBEAFE`	Backgrounds for emphasis
`color-accent`	Secondary accent	`#4F46E5`	Icons, small emphasis
`color-bg`	Default page background	`#FFFFFF`	Page backgrounds
`color-surface`	Card / panel background	`#F9FAFB`	Cards, panels, surfaces
`color-border`	Divider / subtle borders	`#D1D5DB`	Borders, dividers
`color-text-main`	Main text	`#111827`	Primary text
`color-text-muted`	Muted/secondary text	`#6B7280`	Secondary text, placeholders

Brand Colors¶

Name	Token	Hex	Usage	Contrast Ratio
Primary	`color-primary`	`#2563EB`	Links, main CTAs, highlights	4.5:1 (AA)
Primary (soft)	`color-primary-soft`	`#DBEAFE`	Backgrounds for emphasis	-
Primary (dark)	`color-primary-dark`	`#1E40AF`	Hover states, emphasis	7.1:1 (AAA)
Accent	`color-accent`	`#4F46E5`	Icons, small emphasis	4.6:1 (AA)
Accent (dark)	`color-accent-dark`	`#4338CA`	Hover states	6.8:1 (AAA)

Neutral / Background Colors¶

Name	Token	Hex	Usage
Background	`color-bg`	`#FFFFFF`	Page backgrounds
Surface	`color-surface`	`#F9FAFB`	Card/panel backgrounds
Surface (elevated)	`color-surface-elevated`	`#F3F4F6`	Elevated surfaces
Border	`color-border`	`#D1D5DB`	Borders, dividers
Border (subtle)	`color-border-subtle`	`#E5E7EB`	Subtle borders

Semantic Colors (Success, Warning, Error, Info)¶

Semantic Role	Token	Hex	Usage	Contrast Ratio
Success	`color-success`	`#10B981`	Positive states, checks	3.1:1 (AA Large)
Success (dark)	`color-success-dark`	`#059669`	Success text	4.7:1 (AA)
Warning	`color-warning`	`#F59E0B`	Caution, non-blocking issues	2.6:1 (use with dark text)
Warning (dark)	`color-warning-dark`	`#D97706`	Warning text	5.1:1 (AA)
Error	`color-error`	`#EF4444`	Blocking errors, danger	3.2:1 (AA Large)
Error (dark)	`color-error-dark`	`#DC2626`	Error text	4.8:1 (AA)
Info	`color-info`	`#3B82F6`	Neutral informational callouts	3.8:1 (AA Large)
Info (dark)	`color-info-dark`	`#2563EB`	Info text	4.5:1 (AA)

Usage Guidelines¶

Brand Color Usage: - Use primary for main actions, not for every highlight - Use accent sparingly for secondary actions and icons - Use semantic colors only for their meaning (don't use red for decoration) - Prefer neutral backgrounds with accent colors for emphasis

Accessibility: - All text must meet WCAG AA contrast (4.5:1 for normal, 3:1 for large) - Warning colors require dark text for proper contrast - Test color combinations for accessibility

Tip

Contrast Checking: Always check contrast ratios when using colors. Use primary for main actions, semantic colors only for their meaning. Keep text legible—prefer neutral backgrounds with accent colors for emphasis.

Typography Scale¶

Font Families¶

Role	Preferred Font(s)	Fallback Category	Usage
UI & Body	Inter / Roboto / system sans	sans-serif	UI elements, body text, documentation
Code	JetBrains Mono / Fira Code / Roboto Mono	monospace	Code blocks, inline code, technical content

Font Stack Examples: - Body: Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif - Code: "JetBrains Mono", "Fira Code", "Roboto Mono", "Courier New", monospace

Type Scale¶

Token	Example Size	Line Height	Weight	Usage
`text-xxl`	32px (2rem)	1.2	700	Hero titles
`text-xl`	24px (1.5rem)	1.3	600	Section headings (H2)
`text-lg`	20px (1.25rem)	1.5	600	Subheadings (H3)
`text-md`	16px (1rem)	1.6	400	Body text (default)
`text-sm`	14px (0.875rem)	1.5	400	Meta info, labels
`text-code`	14px (0.875rem)	1.5	400	Inline / block code

Heading Mapping: - # (H1) → text-xxl (32px) - ## (H2) → text-xl (24px) - ### (H3) → text-lg (20px) - #### (H4) → text-md (16px, bold) - ##### (H5) → text-sm (14px, bold) - ###### (H6) → text-sm (14px, bold)

Usage Guidelines¶

Typography Rules: - One primary body size (16px) for readability - Avoid more than 2–3 sizes on a single screen/page - Use consistent line-height and spacing - Headings must follow the scale, not arbitrary sizes - Code uses monospace font family

Important

Typography Scale: Headings in docs and UI must follow the defined scale, not arbitrary sizes. Use one primary body size (16px) for readability, and avoid more than 2–3 sizes on a single screen/page.

Icons and Illustration Style¶

Icon Library and Sources¶

Area	Recommended Source	Notes
Web UI	Lucide / Material Icons	Outline style, 1.5–2px stroke
Docs	Simple inline SVGs	Used sparingly in headings or notes
Diagrams	Mermaid shapes	Minimalism over decoration

Icon Style: - Style: Outline icons with minimal detail - Stroke Weight: 1.5–2px for standard icons - Corner Radius: 2px on internal corners (not sharp, not too rounded) - Grid: 24x24px base grid (for Material Design compatibility) - Palette: Limited palette (primary, muted, semantic where needed)

Icon Usage Guidelines¶

Guidelines: - Prefer outline icons with minimal detail - Limited palette (primary, muted, semantic where needed) - Do not mix radically different icon styles (e.g., outline + heavy filled glyphs) - Use icons to support understanding, not just decoration - Maintain consistent stroke weight and corner treatment

Core Icon Concepts:

Icon	Semantic Meaning	Usage
Factory / Agents	AI Software Factory, orchestration, automation	Factory console, agent management
Microservice	Individual service, module, component	Service catalog, architecture diagrams
SaaS App / Portal	Application, platform, product	Product pages, app switcher
Identity / User	Authentication, user management, access	Identity platform, user settings
Audit / History	Audit trail, logging, compliance	Audit platform, history views
Config / Settings	Configuration, settings, preferences	Config platform, settings pages
Bot / AI Assistant	AI bot, chatbot, assistant	Bot platform, AI features
Integration / Connector	Integration, API, connection	Integration pages, connectors

Tip

Icon Purpose: Icons should support understanding, not just decoration. Use icons consistently and sparingly—prefer outline icons with minimal detail, and don't mix radically different icon styles.

Illustration and Diagram Style¶

Diagram Guidelines: - Use simple shapes, avoid complex artwork - Keep colors aligned with palette (e.g., primary for key nodes, neutral for others) - For MkDocs: Prefer Mermaid diagrams and simple SVGs - Minimalism over decoration

Mermaid Diagram Colors: - Primary color for key nodes/actions - Neutral colors for supporting elements - Semantic colors only for their meaning (success, warning, error, info)

Product Marketing Graphics: - Can be more expressive than technical diagrams - Still respect palette and typography - Maintain brand consistency

Core UI Components¶

Cards¶

Purpose: Grouping related content, summaries, metrics

Structure:

Element	Description	Typography
Container	Uses `color-surface`, subtle border or shadow	-
Title	`text-lg` or `text-md`	Bold (600)
Body	`text-md`	Normal (400)
Meta/Tags	`text-sm`, muted text	Normal (400)

Example Structure:

## Card Title

Card body content with proper spacing and formatting.

**Meta:** Tag 1, Tag 2 | Last updated: 2026-01-01

Styling: - Background: color-surface (#F9FAFB) - Border: color-border (#D1D5DB), 1px - Border radius: radius-md (8px) - Padding: space-md (16px) - Shadow: shadow-sm (subtle elevation)

Callouts and Alerts¶

Purpose: Highlight important information, warnings, tips, decisions

Mapping to MkDocs Admonitions:

Admonition	Purpose	Semantic Color	Usage
`note`	Neutral context	`color-info`	Helpful information, context
`tip`	Best practice	`color-success`	Recommendations, best practices
`important`	Key rules/constraints	`color-primary`	Critical rules, requirements
`warning`	Risks & pitfalls	`color-warning`	Cautions, potential issues
`abstract "Decision"`	Decisions/summary boxes	`color-surface` with accent border	ADRs, BDRs, key decisions

Example Usage:

!!! note
    This is helpful context or background information.

!!! tip
    This is a recommended practice or best practice.

!!! important
    This is a critical rule or requirement that must be followed.

!!! warning
    This is a caution or potential issue to be aware of.

!!! abstract "Decision"
    This summarizes a key decision or architectural choice.

See: Documentation Style Guide for callout usage guidelines.

Tables¶

Purpose: Structured data presentation, comparisons, specifications

Styling Guidelines: - Minimal borders and good spacing - Header row uses stronger font weight (600) and slightly different background (color-surface-elevated) - Alternating rows: color-surface background - Border: color-border (#D1D5DB), 1px - Padding: space-sm (8px) vertical, space-md (16px) horizontal

Example:

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Row 1    | Data     | Value    |
| Row 2    | Data     | Value    |

Timelines and Step Lists¶

Purpose: Process flows, roadmaps, step-by-step guides

Numbered Lists: - Use numbered lists for simple flows - Clear step-by-step instructions - Consistent formatting

Mermaid Timelines: - Use Mermaid for visual timelines and roadmaps - Keep colors aligned with palette - Simple shapes and minimal decoration

Example Step List:

1. **Step One** - Description of first step
2. **Step Two** - Description of second step
3. **Step Three** - Description of third step

Example Mermaid Timeline:

gantt
    title Example Roadmap
    dateFormat YYYY-MM-DD
    section Phase 1
    Task 1 :2026-01-01, 30d
    section Phase 2
    Task 2 :2025-02-01, 30d

Hold "Alt" / "Option" to enable pan & zoom

Applying the Brand in MkDocs¶

Headings and Content Structure¶

Heading Mapping: - # (H1) → text-xxl (32px, weight 700) - ## (H2) → text-xl (24px, weight 600) - ### (H3) → text-lg (20px, weight 600) - #### (H4) → text-md (16px, weight 600) - ##### (H5) → text-sm (14px, weight 600) - ###### (H6) → text-sm (14px, weight 600)

Guidance: - One # per page (page title only) - Clear hierarchy (no skipping levels) - Consistent spacing between sections

See: Documentation Style Guide for documentation structure.

Admonitions and Callouts¶

Usage Guidelines: - Use !!! admonitions for key points - Keep them short and focused - Use appropriate admonition type (note, tip, important, warning, abstract) - At least 1 useful callout per major page (where appropriate)

Example:

!!! important
    This is a critical rule that must be followed.

!!! tip
    This is a recommended practice or best practice.

Tip

Callout Best Practice: Encourage at least 1 useful callout per major page (where appropriate). Use callouts to highlight critical information, best practices, warnings, and decisions.

Code Blocks and Inline Code¶

Styling: - Monospace font (Roboto Mono, JetBrains Mono, or Fira Code) - Subtle background (color-surface or slightly darker) - Limited horizontal spilling (wrap or allow scroll) - Border: color-border, 1px - Border radius: radius-md (8px) - Padding: space-md (16px)

Language Tags: - Use consistent language tags: csharp, yaml, json, bash, mermaid, markdown

Example:

```csharp
public class Example
{
    public string Property { get; set; }
}
```

Diagrams and Mermaid¶

Guidelines: - Use Mermaid for flows, context maps, and timelines - Keep color usage minimal: primary + neutral - Avoid overly complex diagrams with many nodes - Use simple shapes and clear labels

Color Usage: - Primary color for key nodes/actions - Neutral colors for supporting elements - Semantic colors only for their meaning

Example:

flowchart LR
    A[Start] --> B[Process]
    B --> C[End]

    style A fill:#2563EB,color:#fff
    style B fill:#F9FAFB,color:#111827
    style C fill:#2563EB,color:#fff

Hold "Alt" / "Option" to enable pan & zoom

Applying the Brand in Figma¶

Design Tokens and Styles¶

Color Styles: - Create color styles per token in Figma - Naming convention: Color / Primary / Base, Color / Primary / Dark, Color / Semantic / Error - Use consistent naming across all color styles

Text Styles: - Create text styles per type scale - Naming convention: Text / Heading / XL, Text / Body / MD, Text / Code / SM - Include font family, size, weight, and line height

Recommended Naming: - Colors: Color / Primary / Base, Color / Semantic / Error, Color / Neutral / Background - Text: Text / Heading / XL, Text / Body / MD, Text / Code / SM

Layout and Spacing¶

Spacing Scale: - Use consistent spacing scale (4/8/12/16/24/32 px increments) - Base unit: 4px - Apply spacing consistently across layouts

Grid System: - Align to a grid (12-column or similar) for web layouts - Use grid for consistent alignment - Maintain consistent margins and padding

Note

Grid Details: Heavy grid details can live in a future "Layout & Grid" doc. For now, use consistent spacing scale and align to a 12-column grid for web layouts.

Component Library in Figma¶

Master Components: Create master components for:

Cards - Using color-surface, border, shadow
Alert/Callout Boxes - Using semantic colors, consistent styling
Buttons - Primary, secondary, ghost variants
Navigation Elements - Top nav, side nav, breadcrumbs

Component Structure: - Use design tokens defined earlier - Maintain consistent styling across components - Enable variants for different states (hover, active, disabled)

Applying the Brand in SaaS UIs (Blazor/React)¶

Design Tokens in Code¶

CSS Variables (Recommended):

Colors, typography, spacing, etc. should be represented as design tokens (CSS variables, SCSS variables, or theme objects in React).

Example CSS Variables:

:root {
  /* Brand Colors */
  --cs-color-primary: #2563EB;
  --cs-color-primary-dark: #1E40AF;
  --cs-color-primary-soft: #DBEAFE;
  --cs-color-accent: #4F46E5;

  /* Neutral Colors */
  --cs-color-bg: #FFFFFF;
  --cs-color-surface: #F9FAFB;
  --cs-color-border: #D1D5DB;

  /* Text Colors */
  --cs-color-text-main: #111827;
  --cs-color-text-muted: #6B7280;

  /* Semantic Colors */
  --cs-color-success: #10B981;
  --cs-color-warning: #F59E0B;
  --cs-color-error: #EF4444;
  --cs-color-info: #3B82F6;

  /* Typography */
  --cs-font-body: Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
  --cs-font-code: "JetBrains Mono", "Fira Code", "Roboto Mono", monospace;

  /* Spacing */
  --cs-space-xs: 4px;
  --cs-space-sm: 8px;
  --cs-space-md: 16px;
  --cs-space-lg: 24px;
  --cs-space-xl: 32px;

  /* Radius */
  --cs-radius-sm: 4px;
  --cs-radius-md: 8px;
  --cs-radius-lg: 12px;
}

Component Libraries and Frameworks¶

Framework Integration: - You may use Tailwind, MudBlazor, Radix, MUI, etc. - They should be themed to match the ConnectSoft palette and typographic scale - Design tokens should be the source of truth, not framework defaults

Theming: - Override framework defaults with ConnectSoft tokens - Maintain brand consistency across frameworks - Use CSS variables or theme objects for easy updates

Important

Source of Truth: Even if using external UI frameworks (Tailwind, MudBlazor, Radix, MUI), the branding tokens defined in this document should still be the source of truth. Theme frameworks to match ConnectSoft palette and typographic scale.

Example Mapping (CSS/SCSS/Variables)¶

Button Example:

.btn-primary {
  background-color: var(--cs-color-primary);
  color: white;
  padding: var(--cs-space-sm) var(--cs-space-md);
  border-radius: var(--cs-radius-md);
  font-family: var(--cs-font-body);
  font-size: var(--cs-text-md);
  font-weight: 600;
}

.btn-primary:hover {
  background-color: var(--cs-color-primary-dark);
}

Card Example:

.card {
  background-color: var(--cs-color-surface);
  border: 1px solid var(--cs-color-border);
  border-radius: var(--cs-radius-md);
  padding: var(--cs-space-md);
  box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.05);
}

.card-title {
  font-size: var(--cs-text-lg);
  font-weight: 600;
  color: var(--cs-color-text-main);
  margin-bottom: var(--cs-space-sm);
}

.card-body {
  font-size: var(--cs-text-md);
  color: var(--cs-color-text-main);
  line-height: 1.6;
}

React Theme Object Example:

const connectSoftTheme = {
  colors: {
    primary: '#2563EB',
    primaryDark: '#1E40AF',
    accent: '#4F46E5',
    bg: '#FFFFFF',
    surface: '#F9FAFB',
    border: '#D1D5DB',
    textMain: '#111827',
    textMuted: '#6B7280',
    success: '#10B981',
    warning: '#F59E0B',
    error: '#EF4444',
    info: '#3B82F6',
  },
  typography: {
    fontFamily: 'Inter, sans-serif',
    fontCode: '"JetBrains Mono", monospace',
    sizes: {
      xxl: '32px',
      xl: '24px',
      lg: '20px',
      md: '16px',
      sm: '14px',
    },
  },
  spacing: {
    xs: '4px',
    sm: '8px',
    md: '16px',
    lg: '24px',
    xl: '32px',
  },
  radius: {
    sm: '4px',
    md: '8px',
    lg: '12px',
  },
};

Future Extensions and Governance¶

Evolution Areas¶

Potential Extensions: - Dark mode (full dark theme specification) - Additional palettes (if needed for specific products) - Expanded component library - Animation and motion guidelines - Responsive breakpoints and mobile guidelines

Ownership and Change Process¶

Area	Owner Role	Change Process
Colors	Brand/Design Owner	Propose → review → update tokens
Typography	Brand/Design Owner	Same process
Components	Design + Frontend Owners	Sync Figma + codebase
Icons	Design Owner	Design → review → add to library
Documentation	Docs Maintainer	Follow docs style guide

Change Process: 1. Propose change with rationale 2. Review with stakeholders (Dmitry, design owner, frontend owner) 3. Update tokens and documentation 4. Update implementations (Figma, CSS, component libraries) 5. Communicate changes to team

Decision

Brand Authority: Brand & UI Kit is authoritative; all public-facing assets must conform or have a documented exception. Changes to the brand system require review and approval from brand/design owner. All implementations (MkDocs, Figma, SaaS UIs) should reference this document as the source of truth.

Documentation Style Guide - Documentation structure and callout usage
Domains & Branding Overview - Domain brand relationships
AI Domain Strategy - .ai domain branding
IO Domain Strategy - .io domain branding
Dev Domain Strategy - .dev domain branding

Brand and UI Kit¶

Brand Overview and Principles¶

Visual Identity¶

Design Principles¶

Color System¶

Palette Overview¶

Brand Colors¶

Neutral / Background Colors¶

Semantic Colors (Success, Warning, Error, Info)¶

Usage Guidelines¶

Typography Scale¶

Font Families¶

Type Scale¶

Usage Guidelines¶

Icons and Illustration Style¶

Icon Library and Sources¶

Icon Usage Guidelines¶

Illustration and Diagram Style¶

Core UI Components¶

Cards¶

Callouts and Alerts¶

Tables¶

Timelines and Step Lists¶

Applying the Brand in MkDocs¶

Headings and Content Structure¶

Admonitions and Callouts¶

Code Blocks and Inline Code¶

Diagrams and Mermaid¶

Applying the Brand in Figma¶

Design Tokens and Styles¶

Layout and Spacing¶

Component Library in Figma¶

Applying the Brand in SaaS UIs (Blazor/React)¶

Design Tokens in Code¶

Component Libraries and Frameworks¶

Example Mapping (CSS/SCSS/Variables)¶

Future Extensions and Governance¶

Evolution Areas¶

Ownership and Change Process¶

Related Documents¶