Topolo Design Language

What It Is

This page defines the shared visual and interaction language agents and teams should follow when building Topolo web frontends.

It is intentionally generic. It does not describe application features, route maps, product workflows, or domain-specific UI behavior. It defines the foundation: tokens, structure, component styling, theme behavior, and interface rules that should remain consistent across Topolo products.

How It Works

Use this page as the default source of truth before introducing product-specific styling. Product-specific deviations should be additive, rare, and documented in the relevant application handbook inside PlatformApplications/TopoloDocs.

Scope Of This Page

This page is a design-language document, not an application handbook.

It should contain:

• shared visual principles
• token and theme rules
• reusable component geometry
• layout and spacing standards
• interaction and motion rules
• guidance agents can apply across products

It should not contain:

• route names
• feature names
• workflow descriptions
• page-by-page product behavior
• domain-specific UI narratives

1. Visual Theme & Atmosphere

Topolo interfaces should feel calm, operational, and precise. The experience should read as a serious product tool first, not a marketing site and not an art-directed brand experiment. White and deep navy do most of the visual work. Borders, spacing, and typography define hierarchy. Accent color exists, but it is deliberately constrained.

The design language is modern without being flashy. Cards are crisp. Layouts are stable. Controls feel tactile through short motion and small transforms, not through large animation sequences. The UI should be readable quickly, easy to scan, and consistent from page to page.

Topolo products should feel like they belong to the same family even when the feature sets differ. A user moving between Topolo applications should immediately recognize:

• the shell proportions
• the typography rhythm
• the light and dark mode behavior
• the card and form geometry
• the border and elevation system
• the restrained accent strategy

Key Characteristics:

• Inter-based typography with strong display sizes and compact UI text
• Light mode led by white, slate, and navy
• Dark mode led by deep navy and dark slate rather than pure black
• Thin borders and subtle elevation instead of heavy chrome
• A single accent family centered on violet
• Consistent shell geometry: 64px top bar, 256px desktop sidebar, 64px collapsed rail
• Card-first composition for most information layouts
• Motion through lift, scale, fade, and short slide transitions
• Structural consistency across light and dark themes

Foundation Rules

These are the reusable Topolo foundations:

• typography scale
• light and dark token model
• shell layout proportions
• button, input, select, card, and badge geometry
• light-mode badges must keep dark readable text, table and list role or status tags should default to soft filled pills instead of outlined treatments, and role badges should not reuse success styling for ordinary user/member labels
• border, elevation, and motion rules
• theme persistence and root-class theme switching
• first-party app icon rendering through the shared Topolo icon system

These are allowed as product accents, but they must not replace the foundation:

• limited gradient moments
• contextual illustrations or promotional highlights
• specialized focused work modes
• product-specific iconography within the shared shell

Per-service identity hints from Auth config are intentionally narrow. They may influence the app icon, focus-ring emphasis, and optional highlight moments. They must not replace shared primary tokens, accent surface tokens, or the neutral shell palette.

First-Party App Icons

Browser favicons and in-app shell marks for first-party Topolo products must come from the shared icon renderer in PlatformApplications/packages/topolo-ui-kit.

Rules:

• use TopoloAppIcon for first-party app chrome, launchers, and auth/loading surfaces instead of bespoke inline glyphs or placeholder letters
• generate browser assets from the shared renderer so favicon.svg and favicon.ico stay aligned
• when rolling out a new shared icon set, bump the favicon query version in app HTML so custom domains request the fresh asset instead of serving a stale cached object
• do not hand-draw alternate app marks inside individual products unless the canonical design language is updated first

This is the guardrail that keeps Admin, CRM, Forecast, Bytes, Pay, Quro, Agent, Social Studio, and the rest of the suite visually consistent when the brand icon set changes.

Public Share Metadata

Public browser entrypoints for first-party Topolo applications must ship a complete sharing contract in their root HTML.

Required tags:

• title
• meta name="title"
• meta name="description"
• meta property="og:type"
• meta property="og:url"
• meta property="og:title"
• meta property="og:description"
• meta property="og:image"
• meta property="og:image:width"
• meta property="og:image:height"
• meta property="og:image:alt"
• meta property="og:site_name"
• meta name="twitter:card"
• meta name="twitter:url"
• meta name="twitter:title"
• meta name="twitter:description"
• meta name="twitter:image"
• meta name="twitter:image:alt"
• link rel="canonical"

Rules:

• use the live Topolo app hostname as the canonical URL instead of legacy or parked domains
• each first-party app must ship a local public/og-image.png sized for large-link previews
• share titles and descriptions should stay aligned with the Auth service catalog where that catalog already owns the app name, base URL, and launcher description
• legacy or non-public runtimes should not claim a public canonical host they do not actually own
• do not leave products with a plain description tag but no OG or Twitter metadata

2. Color Palette & Roles

Primary Neutrals

• Background Light (#ffffff): Main page canvas and clean surfaces
• Foreground / Ink (#020817): Default text and primary icon color
• Primary Fill (#0f172a): Main CTA color and strongest light-mode emphasis
• Secondary Surface (#f1f5f9): Quiet fills, selected states, utility trays
• Border / Input (#e2e8f0): Borders, dividers, and field outlines
• Muted Text (#64748b): Secondary labels, captions, descriptions, inactive text

Dark Theme Neutrals

• Background Dark (#020817): Main dark-mode canvas
• Foreground Dark (#f8fafc): Default dark-mode text
• Surface Dark (#1e293b): Secondary dark surfaces, panels, and borders
• Muted Text Dark (#94a3b8): Secondary dark-mode copy
• Ring Dark (#cbd5e1): Focus ring in dark mode

Dark-Mode Behavior:

• Dark mode keeps the same structure and proportions as light mode
• The canvas should shift to deep navy, not flat black
• Cards should remain restrained and border-led
• Text contrast should stay high, with muted text moving to slate values rather than low-opacity white
• Primary actions in dark mode use a light fill with dark text
• Accent surfaces in dark mode stay neutral slate and must not become brand-violet pills by default

Semantic Status Colors

• Success Light (#16a34a): Positive states and success messaging
• Success Dark (#22c55e): Positive states in dark mode
• Warning Light (#d97906): Warning or attention-required states
• Warning Dark (#facc15): Warning states in dark mode
• Danger Light (#ef4444): Destructive actions and failures
• Danger Dark (#7f1d1d): Destructive states in dark mode

Accent Colors

• Violet 600 (#7c3aed): Primary accent for emphasis
• Violet 500 (#8b5cf6): Secondary accent state
• Purple 600 (#9333ea): Gradient midpoint when needed
• Pink 600 (#db2777): Gradient tail when needed

Accent Rules:

• Violet is the default Topolo accent family
• Accent should appear as emphasis, not as the base color of the interface
• Gradients are permitted only for intentional highlight moments, never as the default background language
• Sidebar active items, hover fills, muted selections, and utility trays use the shared accent surface token, not product highlight color

Text Roles

• Primary Text Light (#020817): Headings, body, labels on light surfaces
• Secondary Text Light (#64748b): Descriptions, captions, metadata
• Primary Text Dark (#f8fafc): Headings, body, labels on dark surfaces
• Secondary Text Dark (#94a3b8): Descriptions, captions, metadata on dark surfaces

Interactive Roles

• Focus Ring Light (#020817): Default focus ring in light mode
• Focus Ring Dark (#cbd5e1): Default focus ring in dark mode
• Accent Surface (#f1f5f9): Hover and selected backgrounds in light mode
• Backdrop Overlay (rgba(0, 0, 0, 0.5)): Scrims and page-separation overlays
• Top Bar Glass (bg-background/95 with blur): Soft translucent header treatment

Theme Contract

• Standard application surfaces support both light and dark
• Theme defaults to system
• User choice persists in local storage
• Theme application happens through root light / dark classes
• Light and dark modes must preserve the same spacing, component sizing, and information architecture
• Theme changes should affect tokens, not layout logic

Shadows

• Surface 1: 0 1px 2px 0 rgb(0 0 0 / 0.05)
• Surface 2: 0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1)
• Surface 3: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1)
• Surface 4: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)
• Surface 5: 0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1)
• Surface 6: 0 25px 50px -12px rgb(0 0 0 / 0.25)

Color Philosophy:

• Neutrals carry the interface
• Semantic colors carry meaning
• Accent color carries emphasis
• Dark mode is an equal first-class theme, not a visual afterthought

3. Typography Rules

Font Family

• Primary: Inter, system-ui, sans-serif
• No secondary display font by default
• Hierarchy should come from scale, weight, line-height, and contrast rather than font swapping

Hierarchy

Role	Size	Weight	Line Height	Letter Spacing	Use
Display 2XL	72px (4.5rem)	700	1.1	-0.02em	Rare hero moments
Display XL	60px (3.75rem)	700	1.1	-0.02em	Large page titles or showcase moments
Display LG	48px (3rem)	700	1.1	-0.02em	Section hero headings
Display MD	36px (2.25rem)	700	1.2	-0.02em	Standard page headings
Display SM	30px (1.875rem)	600	1.2	-0.01em	Subheadings
Display XS	24px (1.5rem)	600	1.3	0	Small section headings
Card Title	24px (text-2xl)	600	1	tight	Card headers and module titles
Body	16px (text-base)	400	default	default	Standard content copy
UI Body	14px (text-sm)	400-500	default	default	Navigation, forms, metadata
Caption	12px (text-xs)	400-600	default	default	Fine metadata and secondary notes

Principles

• Display text should be bold, compact, and used sparingly
• Most UI text should live at 14px or 16px
• Supporting text should become muted before becoming tiny
• Long-form content should stay left aligned in application shells
• Large headings should not appear on every page; the scale should retain meaning
• Standard application pages should use task titles rather than personalized hero copy unless the page is intentionally onboarding or celebratory

4. Component Stylings

Buttons

Primary Default

• Background: #0f172a
• Text: #f8fafc
• Height: 40px
• Padding: 0 16px
• Radius: 6px
• Font: Inter, 14px, weight 500
• Hover: darkens slightly
• Motion: whileHover scale(1.02), whileTap scale(0.98)
• Focus: 2px ring with offset
• Use: primary actions, confirm, create, continue

Secondary

• Background: #f1f5f9
• Text: #020817
• Height: 40px
• Radius: 6px
• Hover: slightly darker surface
• Use: contained secondary actions

Outline

• Background: transparent
• Text: #020817
• Border: 1px solid #e2e8f0
• Height: 40px
• Radius: 6px
• Hover: #f1f5f9 background
• Use: utilities, filters, low-priority actions

Ghost

• Background: transparent
• Text: inherits foreground
• Hover: #f1f5f9
• Use: low-emphasis controls in dense UI

Link

• Background: transparent
• Text: primary or accent as needed
• Decoration: underline on hover
• Use: inline actions and lightweight navigation

Status Buttons

• Success: green background with light text
• Warning: amber background with light text
• Danger / Destructive: red background with light text
• Use: stateful or irreversible actions

Button Sizes

• Small: 36px height, 12px horizontal padding
• Default: 40px height
• Large: 44px height, 32px horizontal padding
• XL: 48px height, 40px horizontal padding, 16px text
• Icon: 40x40px

Cards & Containers

• Background: #ffffff
• Text: #020817
• Border: 1px solid #e2e8f0
• Radius: 8px
• Default Shadow: shadow-sm
• Header Padding: 24px
• Body Padding: 24px
• Entrance: opacity 0 -> 1, y 20 -> 0, 0.3s
• Hover: y -2px
• Use: modules, summaries, forms, overview panels, lists

Dark-Mode Card Rule:

• Cards should remain restrained in dark mode
• Use border-led separation instead of bright floating panels

Card Philosophy:

• Cards are the primary organizational unit
• Borders matter more than shadows
• Card density should stay readable, not cramped

Inputs

• Height: 40px
• Background: #ffffff
• Border: 1px solid #e2e8f0
• Radius: 6px
• Padding: 0 12px
• Font: Inter, 14px
• Placeholder: muted text color
• Focus: 2px ring plus offset, subtle scale(1.01)
• Use: forms, filters, settings, search, structured inputs

Textareas

• Match input styling
• Use the same radius and border treatment
• Maintain generous internal padding
• Avoid heavy inner shadows or custom chrome

Selects

• Trigger height: 40px
• Background: #ffffff
• Border: 1px solid #e2e8f0
• Radius: 6px
• Text: 14px
• Content: bordered popover surface with shadow
• Open/close motion: zoom plus directional slide
• Use: structured option selection

Switches, Checkboxes, Sliders

• Follow the same token system as other controls
• Accent should appear only in active or focused states
• Track size and handle size should feel deliberate and touch-safe

Badges & Chips

• Shape: full pill
• Padding: px-2.5 py-0.5
• Font: 12px, weight 600
• Variants: default, secondary, outline, success, warning, danger, destructive
• Use: status, metadata emphasis, context labels
• In light mode, badge text must stay high-contrast against the fill; avoid pale pastel-on-pastel combinations
• Role badges should not reuse success styling for ordinary user/member labels; reserve success coloring for actual positive state

Navigation

Sidebar

• Desktop width: 256px
• Collapsed width: 64px
• Background: surface with right border
• Item layout: icon plus label, 14px text, 20px icon
• Active item: accent surface fill with accent foreground in both themes
• Inactive item: muted text
• Mobile: slide-over panel with dark scrim
• In dark mode, active items remain neutral slate rather than bright brand-violet

Top Bar

• Height: 64px
• Background: soft translucent surface with blur
• Border: bottom border using the standard border token
• Content: navigation context on the left, utilities on the right
• Utility buttons: square outline controls with comfortable spacing
• App-local command palettes, when present, use Cmd/Ctrl+K and search the current application’s routes or actions
• App-local command palettes should expose the application’s highest-frequency create flows, self/profile actions, and operational shortcuts; they should not collapse into a duplicate of top-level sidebar navigation
• The default shell theme control should be a direct light/dark toggle button rather than a multi-option dropdown unless system-theme selection is explicitly required
• Global search, when present, lives in the top utility bar instead of becoming a second page-header hero
• Desktop shells should keep the top utility bar persistent above the scrollable content area
• If the shell exposes the shared app launcher, mount the launcher overlay once at the shell root rather than inside a conditional sidebar or header branch
• The shared app launcher shortcut is Cmd/Ctrl+Shift+K and it must work in every viewport and sidebar state where the launcher exists

Shell Framing

• Do not add a second outer max-width frame around the whole application shell
• The shell provides edge-to-edge structure; page content containers own local width and padding
• Keep light and dark shells structurally identical

Context Selector

• Width: around 200px
• Visual style: outline button with truncation and chevron
• Use: account, workspace, tenant, or project context where needed

Popover / Utility Panels

• Width should be compact and predictable
• Use title, short content stack, and one footer action at most
• Prefer quick awareness and action, not full-page complexity inside popovers

Reusable Page Patterns

Metric Card

• Compact header row
• 14px title, muted icon, 24px numeric value
• Small delta or supporting row beneath
• Use: overview and reporting surfaces

Application Page Header

• Use a task or surface title such as Dashboard, Settings, or Users
• Subtitle should be concise and operational
• Right side may contain one or two primary utilities or actions
• Breadcrumb context belongs in the shell top bar rather than a second heavy header treatment
• Do not use greeting hero blocks by default

Dashboard Overview

• Default structure is: page header, metric row, then one or more content cards
• Common content split is 2/1 or balanced two-column cards on desktop
• Cards should feel like steady operational modules rather than marketing panels
• Highlight cards are optional and must be rare

Overview Grid Card

• Icon tile, title, description, and a short supporting list
• Hover should suggest navigation, not drag behavior
• Use: overview dashboards, settings hubs, feature indexes

Split Workspace

• Narrower control/input column plus larger content/output column
• Use: creation, editing, generation, review, analysis
• Dark mode should preserve the exact structure and only invert tokens

Focused Workspace

• Use when a task requires higher concentration than the standard app shell
• May use darker surfaces, centered primary canvas, or stronger contrast
• Must still follow shared spacing, typography, and control geometry

5. Layout Principles

Spacing System

• Base unit: 4px
• Comfortable cadence: 8px
• Common steps: 4px, 8px, 12px, 16px, 24px, 32px, 48px
• Dense UI can use 4px and 8px
• Section and card rhythm should usually use 16px and 24px

Grid & Container

• Top bar: 64px
• Desktop shell: sidebar plus main canvas
• Main content padding: 16px mobile, 24px desktop
• Grids should collapse cleanly without changing component geometry
• Search and utility affordances can expand at wider breakpoints, but should stay structurally consistent

Whitespace Philosophy

• Compact does not mean cramped
• Spacing should signal structure before decoration does
• Long forms should be broken into bounded sections or cards
• Empty space should improve scanability, not just fill the screen

Border Radius Scale

• Tight (6px): buttons, inputs, selects
• Standard (8px): cards, popovers, menus
• Round (9999px): badges and pills
• Circular (50%): avatar and icon circles

Information Architecture Philosophy

• Start with overview, then drill into detail
• Keep navigation stable across the product
• Keep settings and configuration structurally separate from primary work surfaces
• Use focused modes only when the task genuinely benefits from them

Loading State Philosophy

• Loading states should mirror the final shell geometry first
• Skeletons should preserve the eventual card and header structure
• Avoid introducing decorative motion that is absent from the resolved interface
• Static placeholders are preferred over animated shimmer for standard admin/product shells

6. Depth & Elevation

Level	Treatment	Use
Level 0	Flat background	Page canvas and quiet surfaces
Surface 1	0 1px 2px 0 rgb(0 0 0 / 0.05)	Light separation
Surface 2	0 1px 3px 0 rgb(0 0 0 / 0.1), 0 1px 2px -1px rgb(0 0 0 / 0.1)	Default elevated surfaces
Surface 3	0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1)	Larger or more important surfaces
Surface 4	0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)	Dialog-level presence
Surface 5	0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1)	Strong modal emphasis
Surface 6	0 25px 50px -12px rgb(0 0 0 / 0.25)	Rare hero or showcase depth

Depth Philosophy:

• Most surfaces should live at Level 0 to Level 2
• Borders and contrast do more work than shadow
• Motion and layering should create depth before shadow does
• Across themes, borders matter more than shadow

Special Depth Elements:

• header glass
• overlay scrims
• popovers and menus
• dialog and modal layers

7. Do’s and Don’ts

Do

• Use Inter with the shared type scale
• Keep page headings in the Display MD / Display SM range for standard application pages
• Use #0f172a as the primary light-mode action color
• Use violet as the default accent family
• Keep light and dark modes structurally identical
• Use cards as the default organizational pattern
• Use semantic green, amber, and red for system meaning
• Preserve the shared shell proportions
• Use short, tactile motion
• Keep product-specific styling additive to the foundation

Don’t

• Don’t turn the app into a gradient-heavy marketing site
• Don’t use accent color as the default color of every control
• Don’t redesign page structure per theme
• Don’t use large radii beyond the shared system except for pills and circles
• Don’t rely on heavy shadow stacks
• Don’t mix unrelated visual languages across Topolo apps
• Don’t add long or theatrical transitions
• Don’t replace semantic status colors with decorative brand shades

8. Mobile Experience Standards

Mobile-First Principle

• Every Topolo application should treat phone-sized use as a first-class product surface, not a collapsed desktop fallback
• Mobile layouts should feel deliberate, calm, and thumb-friendly
• The mobile experience should preserve the same information hierarchy as desktop while simplifying chrome and reducing competing utilities

Breakpoints

Name	Width	Key Intent
Phone Small	<390px	Tightest handset support
Phone Standard	390px-639px	Default handset layout
Tablet / Narrow	640px-1023px	Expanded touch layout
Desktop	>=1024px	Persistent desktop shell

Mobile Shell Rules

• Phones should not show the persistent desktop sidebar
• Primary navigation on phones should use either a slide-over menu or a bottom navigation bar, not both by default
• Use bottom navigation only when the app has 3-5 high-frequency primary destinations
• Use a top app bar for title, context, and one or two critical utilities
• The mobile top app bar should preserve the current-surface label and should not carry more than two utility actions beside the menu trigger
• Secondary utilities should move into an overflow menu, sheet, or modal rather than crowding the top bar
• Respect safe-area insets on top and bottom fixed chrome

Mobile Layout Rules

• Phone screens default to a single-column content flow
• Two-up layouts on phones are allowed only for compact metric cards that remain legible and touch-safe
• Page padding should usually be 16px on phones and 20px-24px on tablets
• Card gaps should usually be 12px on phones and 16px-24px above that
• Avoid side-by-side desktop control bars on phones; stack controls vertically or move them into sheets

Mobile Navigation & Actions

• Keep the primary action reachable without forcing a full-page scroll when the task depends on it
• Sticky mobile action bars are appropriate for creation, approval, checkout, publish, and save flows
• Destructive or low-frequency actions should move behind menus, sheets, or detail views on phones
• Breadcrumb chains should collapse to a single back affordance or current-surface label on phones

Mobile Components

• Minimum touch target: 44x44px
• Inputs and selects should remain at least 40px tall, with 44px preferred for touch-heavy flows
• Compact metric cards on phones must keep the value, label, and supporting change text readable without arbitrary truncation
• Tables should become stacked cards, grouped rows, or focused detail views on phones
• Shared data-table card mode should treat the first column as the primary identity block and move remaining fields into labeled stacked rows
• Filters should become drawers, sheets, or modal panels on phones instead of horizontal desktop toolbars
• Search-heavy list pages should collapse into a stacked search field, a single filter trigger, and a short result-count summary on phones
• Dialogs should become bottom sheets or full-screen overlays on phones when content or actions are dense
• Dense multi-step forms should use explicit sections and sticky footer actions on phones
• Primary save or publish actions for dense edit forms should live in a sticky bottom action bar on phones rather than in a crowded header row
• Cross-suite app launcher surfaces should use a dedicated mobile layout with stacked brand/search/filter rows instead of a compressed desktop header
• Launcher source filters on phones should collapse to compact icon-plus-count pills with accessible labels instead of full text pills or floating count badges
• Empty launcher source filters should drop away on phones when they add no useful state
• Launcher app cards may use a two-up phone grid when the icon, name, and primary action affordance remain legible; secondary copy should clamp cleanly and low-value actions should drop away before cards become crowded

Mobile Typography

• Mobile page titles should generally stay in the 24px-30px range
• Supporting copy should remain concise and avoid multi-line UI clutter in top bars and action rows
• Metadata and helper copy should mute before shrinking below readable size

Mobile Motion & Performance

• Mobile motion should be shorter and simpler than desktop motion
• Avoid large blur fields, heavy box-shadow stacks, and decorative transitions that slow low-power devices
• Skeletons should mirror the mobile layout that will resolve, not the desktop layout
• Keep above-the-fold mobile content focused on the primary task and the first useful data block

Mobile QA Standard

• Validate each application at minimum on 390x844, 430x932, and 768x1024
• Validate light and dark mode
• Validate safe-area behavior, keyboard overlap, fixed action bars, and scroll restoration
• Validate at least one auth flow, one dashboard/list flow, one detail flow, and one form/action flow per app

9. Responsive Behavior

Breakpoints

Name	Width	Key Changes
Mobile Small	<640px	Single column, compact utilities
Tablet / Narrow	640px-1023px	More breathing room, still compact navigation model
Desktop	1024px-1279px	Persistent sidebar, full desktop shell
Wide Desktop	1280px-1535px	Expanded utility spacing and wider content rhythm
Large Desktop	>=1536px	More outer margin, same component rules

Collapsing Strategy

• Sidebar hides below lg and becomes a mobile panel
• Search and utility affordances can collapse to icon-first presentation
• Main content padding decreases on smaller screens
• Grids collapse before components resize unpredictably
• Focused workspaces should simplify before they reflow into complex stacked chrome

Touch Targets

• Small button: 36px minimum
• Default control: 40px
• Primary large action: 44px-48px
• Icon buttons: 40x40px

Media Behavior

• Media should sit inside the shared radius system
• Images and media blocks should scale responsively without changing the layout language
• Dense work surfaces should keep controls simple when media is present

10. Agent Prompt Guide

Quick Color Reference

• Page background: #ffffff
• Page foreground: #020817
• Primary CTA: #0f172a
• Accent: #7c3aed
• Optional gradient: #7c3aed -> #9333ea -> #db2777
• Secondary surface: #f1f5f9
• Border / Input: #e2e8f0
• Muted text: #64748b
• Success: #16a34a
• Warning: #d97906
• Danger: #ef4444
• Dark background: #020817
• Dark surface: #1e293b
• Dark foreground: #f8fafc
• Dark primary action: #f8fafc with dark text

Example Component Prompts

• “Create a Topolo metric card with white background, 1px #e2e8f0 border, 8px radius, subtle shadow, 24px padding, 14px muted title, and a 24px semibold value.”
• “Design a Topolo primary button: background #0f172a, text #f8fafc, 40px height, 16px horizontal padding, 6px radius, Inter 14px weight 500, with a small hover scale and 2px focus ring.”
• “Build a Topolo overview card: soft icon tile, title, description, and four short supporting items, using an 8px radius card with thin border and light hover lift.”
• “Create a Topolo app shell: 64px translucent top utility bar, 256px left sidebar on desktop, muted navigation with active items on the accent surface token, and 24px page padding.”
• “Design a Topolo split workspace: narrower control column on the left, larger output canvas on the right, standard cards, 6px input radii, 8px card radii, and restrained motion.”
• “Design a Topolo mobile layout: single-column flow, 16px horizontal padding, thumb-safe 44px controls, reduced top-bar chrome, and fixed bottom actions only when the task depends on them.”
• “Design Topolo loading placeholders that match the real shell layout and stay static rather than decorative.”

Iteration Guide

1. Start with the foundation system, not with product accents
2. Keep the standard palette neutral and let violet handle emphasis
3. Use 6px radii for controls and 8px radii for cards
4. Prefer 14px UI copy and 36px page headings in standard application views
5. Keep motion under 0.3s and under 2-3px of visible movement where possible
6. Keep light and dark modes structurally identical
7. Add gradients or strong accents only after the shared shell and tokens are respected
8. Start mobile layouts from the phone experience instead of shrinking desktop UI after the fact
9. If a design choice weakens consistency across Topolo apps, it is probably the wrong choice

Interfaces

• canonical shared design-language page: PlatformApplications/TopoloDocs/src/content/internal/platform/design-language.mdx
• mobile rollout plan: PlatformApplications/TopoloDocs/src/content/internal/platform/mobile-experience-rollout.mdx
• suite discovery entrypoint in admin docs: PlatformApplications/TopoloDocs/src/content/internal/apps/admin.mdx
• current implementation references:
  • PlatformApplications/TopoloSocialize/apps/web/src/styles/tokens.css
  • PlatformApplications/TopoloSocialize/apps/web/tailwind.config.ts
  • PlatformApplications/TopoloSocialize/apps/web/src/components/ui/button.tsx
  • PlatformApplications/TopoloSocialize/apps/web/src/components/ui/card.tsx
  • PlatformApplications/TopoloSocialize/apps/web/src/components/ui/input.tsx
  • PlatformApplications/TopoloSocialize/apps/web/src/components/ui/select.tsx
  • PlatformApplications/TopoloSocialize/apps/web/src/components/ui/badge.tsx
  • PlatformApplications/TopoloSocialize/apps/web/src/components/ui/theme-toggle.tsx
  • PlatformApplications/TopoloSocialize/apps/web/src/lib/theme.tsx
  • live light/dark verification on /design-system

Data Flow

1. This page defines the shared Topolo frontend baseline.
2. The Topolo Admin handbook points builders to this page when they need suite-wide UI/UX guidance.
3. Application handbooks inherit this baseline and should document only additive product-specific exceptions.
4. Implementation repos consume the baseline through shared tokens, components, spacing rules, and theme behavior.

Failure Modes

• app-local design files drift away from the canonical docs version
• application handbooks start redefining the shared visual foundation instead of documenting exceptions
• teams treat feature-specific UI patterns as cross-suite design rules
• theme, spacing, or component geometry diverges between apps without being documented here first
• implementation tokens change without this page being updated

Debugging

• start with this page for the current Topolo frontend baseline
• use the Topolo Admin handbook as the discovery path for internal teams and agents
• confirm that app handbooks describe additive exceptions instead of redefining the shared foundation
• inspect the current token and component source before changing shared rules
• run npm run validate from PlatformApplications/TopoloDocs after updating the canonical doc

Change Log / Verification

• Added the shared public-share contract on 2026-04-07 so first-party Topolo apps now require complete OG/Twitter/canonical metadata, local og-image.png assets, and live-host alignment instead of drifting app-by-app
• Added explicit mobile-first shell, layout, component, QA, and rollout-reference rules on 2026-04-06 so every Topolo app now has a canonical phone/tablet standard before app-by-app migration begins
• Refined the mobile component contract on 2026-04-06 after the first Admin rollout so shared phone behavior now explicitly covers top-app-bar density, stacked table cards, collapsed search/filter bars, and sticky bottom form actions
• Tightened the shell and mobile rules again on 2026-04-06 so the canonical design language now prefers a direct theme toggle, forbids truncating compact metric-card content on phones, and requires a dedicated mobile layout for the shared app launcher
• Added explicit shell-composition, dark primary-action, active-navigation, and loading-state rules on 2026-04-06 so future Topolo app work starts from the Socialize-derived shell structure instead of inferring it from tokens alone
• Moved the cross-application design language out of PlatformApplications/TopoloSocialize/design.md into canonical docs on 2026-04-06
• Expanded the older platform brand-baseline coverage into a full shared design-language spec on 2026-04-06
• Linked the Topolo Admin handbook to this page as the suite-wide frontend reference on 2026-04-06