DESIGN.md

metadata

name: Senti AI Design System
description: >-
  Visual specifications for personal, business, and institutional banking
  modules.
colors:
  primary-personal: '#50fa7b'
  primary-inst: '#38bdf8'
  bg-personal: '#0e1322'
  bg-inst: '#0b1326'
  ink-personal: '#dee1f7'
  ink-inst: '#dae2fd'
  outline: '#859583'
  error: '#ffb4ab'
typography:
  display:
    fontFamily: DM Serif Display, serif
    fontSize: clamp(2rem, 5vw, 4.5rem)
    fontWeight: 400
    lineHeight: 1.1
    letterSpacing: '-0.02em'
  headline:
    fontFamily: IBM Plex Sans, sans-serif
    fontSize: 1.75rem
    fontWeight: 600
    lineHeight: 1.25
  title:
    fontFamily: IBM Plex Sans, sans-serif
    fontSize: 1.25rem
    fontWeight: 500
    lineHeight: 1.3
  body:
    fontFamily: IBM Plex Sans, sans-serif
    fontSize: 1rem
    fontWeight: 400
    lineHeight: 1.5
  label:
    fontFamily: IBM Plex Mono, monospace
    fontSize: 0.875rem
    fontWeight: 500
    letterSpacing: 0.05em
rounded:
  personal: 16px
  business: 8px
  institutional: 4px
spacing:
  sm: 8px
  md: 16px
  lg: 24px
  xl: 32px
components:
  button-personal:
    backgroundColor: '{colors.primary-personal}'
    textColor: '{colors.bg-personal}'
    rounded: '{rounded.personal}'
    padding: 12px 24px
  button-inst:
    backgroundColor: '{colors.primary-inst}'
    textColor: '{colors.bg-inst}'
    rounded: '{rounded.institutional}'
    padding: 8px 16px
  card-personal:
    backgroundColor: '{colors.bg-personal}'
    rounded: '{rounded.personal}'
    padding: 24px
  card-inst:
    backgroundColor: '{colors.bg-inst}'
    rounded: '{rounded.institutional}'
    padding: 16px

Senti AI Design System

1. Overview

Creative North Star: "The Neon Ledger & Cyber Observatory"

Senti AI features a dual-natured visual architecture tailored to its target audiences. Personal and business modules operate under The Neon Ledger, a progressive, highly kinetic dark environment that bridges everyday mobile money patterns with futuristic wealth tools. Institutional and regulatory modules occupy The Cyber Observatory, an ultra-dense, highly structured dashboard environment focused on mathematical certainty, risk tracking, and compliance.

The system is flat-by-default, rejecting gratuitous three-dimensional gradients or shadows in favor of crisp borders, purposeful color states, and high readability. It enforces a strict visual grammar that keeps components clean, preventing layout noise and making the complex financial data feel clear and intuitive.

Key Characteristics:

• Double Identity: Dynamic slate-green for personal/business; obsidian-blue for institutional.
• Earned Density: Clean grids and structured layouts designed to convey financial data clearly.
• Clinical Math: Strict separation between analytical values (highlighted in monospace fonts) and dynamic dialogue interfaces.

2. Colors

Colors in Senti AI are semantic, functional, and highly restricted. Senti personal modules are dark-emerald committed, while Senti institutional modules are restrained cyber-blue.

Primary

• Emerald Glow (#50fa7b / oklch(86.83% 0.28 142.5)): Used exclusively for primary buttons, active chat bubbles, success indicators, and positive cash flows in personal modules.
• Cyber Azure (#38bdf8 / oklch(76.2% 0.16 230.1)): Used for primary actions, loan approval tags, and compliance statuses in institutional modules.

Neutral

• Slate Void (#0e1322): Primary background surface for personal/business views.
• Deep Obsidian (#0b1326): Structural background surface for institutional views.
• Silver Silk (#dee1f7): High-contrast primary ink/text color for personal modules.
• Cyber Glass (#dae2fd): High-contrast primary ink/text color for institutional modules.

Named Rules

The Rarity of Glow Rule. Senti Neon (#50fa7b) must occupy no more than 10% of any personal screen view. Rarity is what gives primary actions and positive status indicators their authority. The Dual Tenant Rule. A personal dashboard element must never use Cyber Azure (#38bdf8) accents, and an institutional dashboard must never display Emerald Glow (#50fa7b) button assets. Brand identity is structurally bound to the path.

3. Typography

Typography in Senti AI divides display, interface, and tabular data strictly to balance emotional warmth with mathematical rigor.

Display Font: DM Serif Display (serif fallback) Body Font: IBM Plex Sans (sans-serif fallback) Label/Mono Font: IBM Plex Mono (monospace fallback)

Character: Display headings pair a traditional, academic serif with an ultra-clean, technical sans-serif to create an "expert confidence" feel. Monospaced elements are heavily prioritized for tabular metrics and financial indicators to guarantee strict columnar alignment.

Hierarchy

• Display (Regular 400, clamp(2rem, 5vw, 4.5rem), Line-Height 1.1): Used strictly for marketing hero headings and main dashboard welcome banners.
• Headline (Semi-Bold 600, 1.75rem, Line-Height 1.25): Used for main card groupings and page section titles.
• Title (Medium 500, 1.25rem, Line-Height 1.3): Used for subheadings and card titles.
• Body (Regular 400, 1rem, Line-Height 1.5): Standard prose and message bubbles. Limited to 65–75 characters per line (max-w-[70ch]).
• Label (Medium 500, 0.875rem, Letter-Spacing 0.05em, Uppercase): Monospaced label tag used for table headers, financial calculations, and state alerts.

Named Rules

The Monospace Tabular Rule. All financial numbers, interest calculations, currency listings (KES, USD), and tax amounts must be wrapped in monospaced formatting (font-mono) to prevent visual layout shifting during real-time calculation updates.

4. Elevation

Senti AI strictly rejects drop-shadows on border-wrapped containers to avoid the outdated "ghost-card" anti-pattern. Depth is created via tonal surface layering and crisp, low-opacity outline borders.

• Flat Layering: Content surfaces use elevated background steps (senti-surface-container #1a1f2f on bg #0e1322) rather than shadows to define panels.
• State Glow: Subtle ambient glows (box-shadow: 0 0 10px rgba(80, 250, 123, 0.3)) are reserved exclusively for active, real-time recalculating indicators or positive chat state cues (neon-glow).

Named Rules

The Flat Rest Rule. Containers, buttons, and panels are completely flat at rest. Low-blur shadows appear only as a highly responsive transition during active hover and focus states.

5. Components

Buttons

• Shape: Rounded according to segment constraints (Personal = 16px rounded; Institutional = 4px sharp).
• Personal Primary: Emerald Glow background with Slate Void text, padded at 12px 24px.
• Institutional Primary: Cyber Azure background with Deep Obsidian text, padded at 8px 16px.
• Hover/Focus State: 150ms transition. Shifts background brightness or scales down slightly (scale-98) under click pressure.

Cards / Containers

• Corner Style: Matching segment rounded scales (Personal = 16px, Business = 8px, Institutional = 4px).
• Background: Raised surface containers (Personal = #1a1f2f; Institutional = #171f33).
• Borders: Thin structural borders (1px solid rgba(255,255,255,0.08) or {colors.outline}). No side-stripe accents allowed.

Inputs / Fields

• Style: Background container (#0e1322 / #060e20), thin outline, and segment-specific corner radii.
• Focus: 150ms transition. Glow border transition to primary accent color (#50fa7b or #38bdf8).

Navigation

• Style: Flat side nav with high contrast indicators. Selected states are denoted by a solid outline ring or a low-opacity container fill, never by a side-stripe vertical bar.

6. Do's and Don'ts

Do:

• Do wrap every financial amount, table row, and exchange rate in font-mono to ensure tabular alignment and prevent layout shifting.
• Do strictly limit Senti Neon (#50fa7b) to primary action triggers and real-time computation states, respecting the Rarity rule.
• Do support prefers-reduced-motion, swapping kinetic panel slides for instant or soft opacity fades when selected.
• Do maintain a minimum 4.5:1 contrast ratio for all secondary label and placeholder texts against background containers.

Don't:

• Don't use diagonal stripe backgrounds, paper textures, or hand-drawn sketches. Maintain high-tech vector precision.
• Don't combine a 1px border with a soft drop shadow on cards or buttons (ghost-card anti-pattern). Pick one.
• Don't apply vertical or horizontal side-stripes (border-left or border-top > 1px) to represent container accents on rounded cards.
• Don't allow hero headings or modal dialogue titles to exceed 6rem clamp sizes.
• Don't implement animate-bounce or elastic transition easing. Decelerate smoothly using exponential curves.

7. Motion & Interaction

Custom Easing Curves (Design Tokens)

All transitions must use one of these custom curves. Default CSS ease, ease-in-out, and linear are banned for UI animations.

• Exponential Out — cubic-bezier(0.23, 1, 0.32, 1) (--ease-out-expo): Primary UI easing. Used for color changes, hover states, popover entry, and all general-purpose transitions. Starts fast, giving instant feedback.
• Exponential In-Out — cubic-bezier(0.77, 0, 0.175, 1) (--ease-in-out-expo): Used for on-screen element movement, state morphing, and continuous pulses.
• Drawer Curve — cubic-bezier(0.32, 0.72, 0, 1) (--ease-drawer): Used for sidebar slide transitions, progress bar fills, and panel open/close.

Duration Guidelines

Element	Duration
Button press feedback	160ms
Tooltips, small popovers	125–200ms
Hover color changes	150ms
Dropdowns, selects	150–250ms
Modals, drawers, panels	200–350ms
Cascade stagger per-item	30–80ms delay

Press Feedback Standard

Every interactive button must include tactile press feedback via transform: scale(0.97) on :active, using the btn-press utility class. This applies universally across personal, business, and institutional modules.

Cascade Stagger Reveals

Lists, card grids, and navigation items must never mount instantly. Use staggered delays:

• Grid cards: stagger-item class — 40ms intervals, fadeSlideIn keyframe.
• Navigation items: stagger-nav class — 30ms intervals, tighter fadeSlideIn.
• Stagger is decorative — never block interaction during playback.

Modal Entry Animation

• Overlay: modal-enter — 200ms opacity fade.
• Panel: modal-panel-enter — 250ms fade + scale(0.96) to scale(1).
• Modals use transform-origin: center (they are viewport-anchored, not trigger-anchored).

Performance Rules

• Animate exclusively via transform and opacity. Never animate top, left, width, height, margin, or padding.
• backdrop-blur is only applied to fixed or sticky elements (navbars, overlays). Never to scrolling content.
• Use CSS transitions over keyframes for interruptible UI. Keyframes restart from zero; transitions retarget smoothly.
• Noise/grain filters must be on fixed, pointer-events: none pseudo-elements only.
• Specify exact transition properties — transition: all is banned.

Accessibility

• Respect prefers-reduced-motion: reduce. All transform and position animations are stripped; opacity fades are retained.
• Gate hover effects behind @media (hover: hover) and (pointer: fine) on touch devices.
• Minimum 44px touch targets for all interactive elements.

8. Anti-Patterns (Banned)

The following patterns are banned across all modules:

• Emojis in code or rendered output
• transition: all — specify exact properties
• ease-in on any UI element — feels sluggish
• animate-pulse or animate-bounce — use alert-pulse for subtle indicator animations
• shadow-md or generic drop shadows — use custom shadow-[0_1px_3px_rgba(0,0,0,0.3)]
• border-l side-stripe accents on rounded containers (personal/business) — use ring-1 or tonal fill
• scale(0) entry animations — start from scale(0.95) + opacity: 0
• Hover animations without media query gating on touch devices
• AI copywriting clichés: "Seamless", "Elevate", "Unleash", "Next-Gen"
• Fake round numbers: 99.99%, 50%
• Generic placeholder names: "John Doe", "Acme", "Nexus"