Skip to content

Latest commit

 

History

History
761 lines (561 loc) · 26.7 KB

File metadata and controls

761 lines (561 loc) · 26.7 KB

HelloData Design Token System

Last Updated: January 2026 Version: 3.6 (Navbar Standardization)

This document defines the spacing and border radius token systems used across all HelloData landing pages. It explains the rationale behind each value, when to use specific tokens, and what should NOT be converted to tokens.


Table of Contents

  1. Design Philosophy
  2. Spacing Token Reference
  3. Border Radius Token System
  4. Usage Guidelines
  5. Intentional Exceptions
  6. Opacity Color Tokens
  7. Line Height Token Reference
  8. Semantic Color Tokens
  9. Version History

Design Philosophy

The 8px Grid System

HelloData uses an 8px base grid for all spacing decisions. This creates:

  • Visual harmony — Elements align naturally across the page
  • Consistent rhythm — Predictable spacing reduces cognitive load
  • Scalable system — Easy to maintain and extend
  • Premium feel — Generous whitespace signals quality and confidence

Why These Specific Values?

The token values follow a geometric progression that creates natural visual hierarchy:

4px  → 8px  → 12px → 16px → 24px → 32px → 48px → 64px → 96px → 112px → 144px
(×2)   (×1.5)  (×1.33) (×1.5)  (×1.33) (×1.5)  (×1.33) (×1.5)  (×1.17) (×1.29)

This non-linear scale provides enough granularity for component-level spacing while creating dramatic jumps for section-level breathing room.

Premium Spacing Philosophy (v2.0)

In January 2025, we increased section-level spacing to create a more premium, spacious aesthetic. The rationale:

  1. More whitespace = more premium — Luxury brands use generous spacing to signal confidence
  2. Improved scroll pace — Users perceive content as more valuable when given room to breathe
  3. Better content hierarchy — Increased section gaps make page structure clearer
  4. Reduced visual fatigue — Less cramped layouts improve readability and comprehension

Spacing Token Reference

Micro Spacing (Component Internal)

Used for tight groupings like icon/text pairs, form elements, and inline elements.

Token Value Use Case
--space-1 4px Icon-to-text gap, tight inline spacing
--space-2 8px Button icon gap, small element margins

Component Spacing

Used for internal padding, element margins within components.

Token Value Use Case
--space-3 12px List item spacing, tag padding
--space-4 16px Standard component padding, form field gaps
--space-5 20px Comfortable internal padding
--space-6 24px Card internal padding, section header margins
--space-8 32px Large component padding, content block gaps

Layout Spacing

Used for grid gaps, card padding, and content block separation.

Token Value Use Case
--space-10 40px Medium content gaps
--space-12 48px Grid gaps, large card padding
--space-14 56px Feature section internal padding
--space-16 64px Large layout gaps
--space-18 72px Mobile section padding
--space-20 96px Section internal padding, large content blocks

Note: --space-20 was increased from 80px to 96px in v2.0 for more breathing room.

Section Spacing

Used for vertical padding between major page sections. These are the highest-impact tokens for overall page feel.

Token Value Use Case
--space-section-sm 112px Lighter sections, secondary content
--space-section-md 144px Standard section padding (most common)
--space-section-lg 160px Featured sections, emphasis areas
--space-section-xl 184px Hero sections, final CTAs

Note: All section tokens were increased in v2.0:

  • --space-section-sm: 96px → 112px (+16px)
  • --space-section-md: 120px → 144px (+24px)
  • --space-section-lg: 140px → 160px (+20px)
  • --space-section-xl: 160px → 184px (+24px)

Hero Section Spacing

Asymmetric padding for visual balance in hero sections.

Token Value Use Case
--space-hero-top 80px Hero section top padding
--space-hero-bottom 80px Hero section bottom padding
--space-hero-top-mobile 48px Mobile hero top padding
--space-hero-bottom-mobile 32px Mobile hero bottom padding

Border Radius Token System

Angular Brand Philosophy (v3.0)

HelloData uses an angular, 3-tier radius system that maintains a technical, professional aesthetic. This system:

  • Prevents over-rounding — Our B2B data platform requires a precise, technical feel
  • Creates visual variety — Three distinct tiers allow appropriate rounding per element type
  • Maintains brand consistency — Angular design signals data-driven professionalism
  • Simplifies decisions — Limited options make choosing the right radius easy

Why Angular?

Consumer products often use generous rounding (16px+) to feel friendly and approachable. HelloData is a B2B enterprise data platform — our brand identity is:

  • Technical precision over casual friendliness
  • Professional confidence over playful approachability
  • Data-driven rigor over decorative softness

Our radius values reflect this: the maximum non-pill radius is 12px, keeping corners crisp and intentional.

Radius Token Reference

Token Value Visual Use Case
--radius-sm 4px Sharp Tags, badges, small elements, code blocks
--radius-md 8px Standard Cards, buttons, inputs, modals
--radius-lg 12px Soft Hero images, feature frames, large containers
--radius-full 100px Pill Eyebrow badges, status indicators only

Usage Guidelines

/* Sharp (4px) - Small UI elements */
.tag { border-radius: var(--radius-sm); }
.badge { border-radius: var(--radius-sm); }
.code-block { border-radius: var(--radius-sm); }

/* Standard (8px) - Most interactive elements */
.card { border-radius: var(--radius-md); }
.button { border-radius: var(--radius-md); }
.input { border-radius: var(--radius-md); }
.dropdown { border-radius: var(--radius-md); }

/* Soft (12px) - Large visual containers */
.hero-image { border-radius: var(--radius-lg); }
.feature-frame { border-radius: var(--radius-lg); }
.modal-large { border-radius: var(--radius-lg); }

/* Pill (100px) - Badges only */
.eyebrow-badge { border-radius: var(--radius-full); }
.status-pill { border-radius: var(--radius-full); }

Decision Tree

Is it a pill-shaped badge/status indicator?
  └─ YES → --radius-full (100px)
  └─ NO → Continue...

Is it a small element (tag, badge, code block)?
  └─ YES → --radius-sm (4px)
  └─ NO → Continue...

Is it a large visual container (hero image, feature frame)?
  └─ YES → --radius-lg (12px)
  └─ NO → --radius-md (8px) [default]

Intentional Radius Exceptions

The following should NOT use radius tokens:

Circular elements:

/* Perfect circles use 50%, not tokens */
.avatar { border-radius: 50%; }
.icon-circle { border-radius: 50%; }

Scrollbar styling:

/* Very small values for scrollbar tracks/thumbs */
::-webkit-scrollbar-thumb { border-radius: 3px; }

Progress bars and decorative lines:

/* Sub-token values for thin decorative elements */
.progress-bar { border-radius: 2px; }
.timeline-line { border-radius: 2px; }

Usage Guidelines

When to Use Each Token Tier

┌─────────────────────────────────────────────────────────────┐
│  SECTION LEVEL (section-sm/md/lg/xl)                        │
│  ┌───────────────────────────────────────────────────────┐  │
│  │  LAYOUT LEVEL (space-12 to space-20)                  │  │
│  │  ┌─────────────────────────────────────────────────┐  │  │
│  │  │  COMPONENT LEVEL (space-3 to space-8)           │  │  │
│  │  │  ┌───────────────────────────────────────────┐  │  │  │
│  │  │  │  MICRO LEVEL (space-1, space-2)           │  │  │  │
│  │  │  │  Icon gaps, inline spacing                │  │  │  │
│  │  │  └───────────────────────────────────────────┘  │  │  │
│  │  │  Card padding, form fields, margins             │  │  │
│  │  └─────────────────────────────────────────────────┘  │  │
│  │  Grid gaps, content blocks, card containers           │  │
│  └───────────────────────────────────────────────────────┘  │
│  Page sections, vertical rhythm between content areas       │
└─────────────────────────────────────────────────────────────┘

CSS Implementation

/* Section padding */
.features-section {
  padding: var(--space-section-md) 0;
}

/* Card internal spacing */
.feature-card {
  padding: var(--space-6);
}

/* Grid layout */
.card-grid {
  gap: var(--space-8);
}

/* Component internal */
.button {
  gap: var(--space-2);
  padding: var(--space-4) var(--space-6);
}

/* Micro spacing */
.icon-text {
  gap: var(--space-1);
}

Responsive Considerations

Section spacing typically reduces on mobile:

.section {
  padding: var(--space-section-md) 0;
}

@media (max-width: 768px) {
  .section {
    padding: var(--space-20) 0;  /* 96px instead of 144px */
  }
}

Intentional Exceptions

The following values are intentionally NOT tokenized. Do not convert these to tokens:

Button Padding

/* Buttons use specific padding for optimal click targets and visual weight */
padding: 14px 28px;  /* Keep as-is — tested for accessibility and aesthetics */

Rationale: Button padding is carefully calibrated for:

  • Minimum 44px touch target height (accessibility)
  • Visual weight balance with 3D shadow effect
  • Consistent feel across all button variants

1px Borders

border: 1px solid var(--color-border);  /* Keep 1px — structural, not spacing */

Rationale: Borders are structural elements, not spacing. The 1px value is standard for UI borders.

UI Mockup Elements

The hero section interface mockups (fake app UIs) use intentionally fine-grained values:

/* These are decorative — mimic real UI proportions */
.hero-app-toolbar { padding: 8px 12px; }
.hero-property-card { padding: 10px 14px; }
.graphic-clean-row { padding: 10px 14px; }

Rationale: These simulate real application interfaces and need pixel-perfect control for visual fidelity.

Media Query Breakpoints

@media (max-width: 768px) { }  /* Keep as-is — standard breakpoint */
@media (max-width: 480px) { }  /* Keep as-is — mobile breakpoint */

Rationale: Breakpoints are not spacing values — they're viewport thresholds.

Max-Width Values

max-width: 1200px;  /* Container constraint — not spacing */
max-width: 640px;   /* Content width limit */

Rationale: Width constraints are layout values, not spacing tokens.

Small Decorative Values

/* Values under 4px are typically decorative or structural */
padding: 2px 6px;   /* Tiny badges */
gap: 6px;           /* Tight icon groups */

Rationale: Sub-4px values are below the grid threshold and used for micro-adjustments.


Opacity Color Tokens

Opacity variants for white, black, and purple colors. Use these instead of hardcoded rgba() values.

White Opacity Variants

Token Value Use Case
--color-white-10 rgba(255, 255, 255, 0.1) Subtle overlays, dark bg hover states
--color-white-20 rgba(255, 255, 255, 0.2) Light borders on dark backgrounds
--color-white-30 rgba(255, 255, 255, 0.3) Semi-visible borders, dividers
--color-white-60 rgba(255, 255, 255, 0.6) Muted text on dark backgrounds
--color-white-70 rgba(255, 255, 255, 0.7) Secondary text on dark backgrounds

Black Opacity Variants

Token Value Use Case
--color-black-05 rgba(0, 0, 0, 0.05) Subtle shadows, light overlays
--color-black-10 rgba(0, 0, 0, 0.1) Standard card shadows, borders
--color-black-20 rgba(0, 0, 0, 0.2) Stronger shadows, modal overlays

Accent Opacity Variants

Token Value Use Case
--color-purple-30 rgba(99, 102, 241, 0.3) Focus rings, purple tints

Line Height Token Reference

Standardized line heights for consistent typography rhythm.

Token Value Use Case
--line-height-tight 1.1 Large headings (H1, H2)
--line-height-snug 1.25 Medium headings, tight body text
--line-height-normal 1.5 Standard body text
--line-height-relaxed 1.6 Comfortable reading, descriptions
--line-height-loose 1.7 Spacious paragraphs, long-form content

Usage Guidelines

/* Headings - use tight or snug */
.heading-1 { line-height: var(--line-height-tight); }
.heading-2 { line-height: var(--line-height-snug); }

/* Body text - use normal or relaxed */
.body-text { line-height: var(--line-height-relaxed); }
.description { line-height: var(--line-height-relaxed); }

/* Long-form content - use loose */
.article-body { line-height: var(--line-height-loose); }

Semantic Color Tokens

Additional semantic colors for backgrounds and borders.

Token Value Use Case
--color-bg-subtle #F3F4F6 Subtle background tint, alternate sections
--color-border-light #E2E8F0 Light borders, dividers
--color-success-bg #ECFDF5 Success state backgrounds
--color-error-bg #FEF2F2 Error state backgrounds

Version History

v3.1 — Opacity & Typography Tokens (January 2025)

Goal: Eliminate hardcoded rgba() and line-height values across all landing pages.

Added:

  • 9 opacity color tokens (--color-white-10/20/30/60/70, --color-black-05/10/20, --color-purple-30)
  • 1 line height token (--line-height-loose: 1.7)
  • 4 semantic color tokens (--color-bg-subtle, --color-border-light, --color-success-bg, --color-error-bg)
  • Breakpoint reference documentation in tokens.css

Migration:

  • Replaced ~985 hardcoded values across 15 landing pages
  • All rgba(255, 255, 255, 0.x)var(--color-white-*)
  • All rgba(0, 0, 0, 0.x)var(--color-black-*)
  • All hardcoded line-height: 1.xvar(--line-height-*)
  • All font-size: 12/14/15/16pxvar(--font-size-xs/sm/base)

v3.2 — Gap Value Tokenization (January 2025)

Goal: Eliminate all hardcoded gap values using existing space tokens.

Added:

  • 1 new spacing token: --space-md-sm: 12px (fills gap between 8px and 16px)

Migration:

  • Replaced ~250 hardcoded gap values across entire codebase
  • Landing pages: All 15 HTML files fully tokenized
  • Library files: hellodata-master-library-v40.html, hellodata-complete-library.html
  • Component snippets: _footer-snippet.html, _nav-snippet.html
  • Preview tool: _preview/index.html

Gap Value Mappings:

Before After
gap: 4px var(--space-xs)
gap: 6px/8px/10px var(--space-sm)
gap: 12px var(--space-md-sm)
gap: 16px var(--space-md)
gap: 20px/24px var(--space-lg)
gap: 32px/40px var(--space-xl)
gap: 48px var(--space-2xl)
gap: 64px var(--space-3xl)

v3.3 — Complete Typography & Layout Tokenization (January 2025)

Goal: Tokenize all remaining hardcoded values where tokens already exist.

Migration:

  • Replaced ~330 hardcoded values across all landing pages and library files
  • Font weights: 110+ instances → var(--font-weight-*)
  • Border radius: 40+ instances → var(--radius-*)
  • Letter spacing: 95+ instances → var(--letter-spacing-*)
  • Line heights: 35+ instances → var(--line-height-*)
  • RGBA colors: 50+ cleanup passes

Value Mappings:

Category Before After
Font Weight 700 var(--font-weight-bold)
Font Weight 600 var(--font-weight-semibold)
Font Weight 500 var(--font-weight-medium)
Border Radius 8px var(--radius-md)
Border Radius 6px var(--radius-sm)
Border Radius 12px var(--radius-lg)
Letter Spacing -0.02em var(--letter-spacing-tight)
Letter Spacing 0.05em var(--letter-spacing-wider)
Letter Spacing 0.1em var(--letter-spacing-widest)

Intentional Exclusions:

  • font-weight: 300 — no light weight token
  • border-radius: 2-3px — below --radius-sm
  • Non-standard letter-spacing (-0.015em, 0.08em)

v3.6 — 100% Edge Case Tokenization (January 2025)

Goal: Complete tokenization of ALL remaining RGBA, letter-spacing, and box-shadow edge cases.

Added:

  • 18 new opacity tokens completing all color scales:
    • White: --color-white-25/40/50/75/80/95
    • Black: --color-black-08/25
    • Purple: --color-purple-08/35/40/50
    • Orange: --color-orange-35/40/45
    • Green: --color-green-10/20 (new success color family)
    • Blue: --color-blue-light-40 (charts/data viz)
  • 1 letter-spacing token: --letter-spacing-ultra-wide: 0.12em
  • 3 shadow tokens: --shadow-deep, --shadow-dot-purple, --shadow-dot-orange

Migration:

  • RGBA colors: 17 → 0 remaining (100% complete)
  • Letter-spacing: 2 → 0 remaining (100% complete)
  • Box-shadows: 18 → 0 remaining (100% complete)

Complete Opacity Token Reference:

Color Available Scales
White 03, 05, 08, 10, 15, 20, 25, 30, 40, 50, 60, 70, 75, 80, 85, 90, 95
Black 05, 08, 10, 15, 20, 25
Purple 03, 05, 08, 10, 15, 20, 25, 30, 35, 40, 50
Orange 20, 35, 40, 45
Green 10, 20
Blue Light 40

v3.5 — Complete Opacity & Edge Case Cleanup (January 2025)

Goal: Complete the opacity token scales and eliminate remaining edge cases.

Added:

  • 14 new opacity tokens across all color scales
  • --letter-spacing-tighter: -0.03em and --letter-spacing-extra-wide: 0.08em
  • --radius-xs: 4px for subtle rounding

Migration:

  • Tokenized ~170 remaining edge case values
  • RGBA colors: 92 → 17 remaining (82% reduction)
  • Box-shadows: 55 → 18 remaining (67% reduction)
  • Letter-spacing: 32 → 2 remaining (94% reduction)
  • Border-radius: 8 → 0 remaining (100% complete)

Intentional Exclusions:

  • Unique opacity values used once (0.4, 0.5, 0.75, 0.8, 0.95)
  • Extra-wide letter-spacing beyond scale (0.12em, 0.14em)
  • Complex compound shadows for specific components
  • #FFFFFF for white text on dark backgrounds

v3.4 — Button Padding & Shadow Tokens (January 2025)

Goal: Tokenize button padding and shadow values for consistent button styling.

Added:

  • 3 button padding tokens (--button-padding-sm/md/lg)
  • 7 shadow tokens (--shadow-purple-sm/glow/glow-lg/glow-xl, --shadow-orange-glow, --shadow-elevated/-light)

Migration:

  • Replaced ~175 button/shadow values across all landing pages and library files
  • Button padding: 56+ instances → var(--button-padding-*)
  • Button shadows: 110+ instances → var(--shadow-btn-*)
  • Purple glow shadows: 5+ instances → var(--shadow-purple-*)
  • Elevated shadows: 2+ instances → var(--shadow-elevated-*)

Token Reference:

Category Token Value
Button Padding --button-padding-sm 10px 20px
Button Padding --button-padding-md 14px 28px
Button Padding --button-padding-lg 18px 36px
Shadow --shadow-purple-sm 0 4px 16px rgba(99, 102, 241, 0.3)
Shadow --shadow-purple-glow 0 20px 40px -12px rgba(99, 102, 241, 0.2)
Shadow --shadow-orange-glow 0 4px 12px rgba(249, 115, 22, 0.3)
Shadow --shadow-elevated 0 4px 20px rgba(0, 0, 0, 0.3)

Intentional Exclusions:

  • Compound button shadows with multiple effects (rent-forecast)
  • Unique glow variations for specific UI elements (map dots, focus rings)

v3.0 — Angular Radius System (January 2025)

Goal: Implement a 3-tier border radius token system aligned with HelloData's angular, technical brand identity.

Changes:

Token Value Purpose
--radius-sm 4px Sharp corners for tags, badges, small elements
--radius-md 8px Standard corners for cards, buttons, inputs
--radius-lg 12px Soft corners for hero images, feature frames
--radius-full 100px Pill shape for eyebrow badges only

Removed:

  • --radius-xl (was 16px) — Consolidated into --radius-lg to prevent over-rounding

Migration:

  • All var(--radius-xl) references updated to var(--radius-lg)
  • Hardcoded border-radius: 100px migrated to var(--radius-full)
  • Hardcoded border-radius: 4px migrated to var(--radius-sm)
  • Hardcoded border-radius: 12px/16px migrated to var(--radius-lg)

Impact:

  • Consistent angular aesthetic across all 15 landing pages
  • Simpler token system (4 tokens vs previous 4-5 inconsistent tokens)
  • Clear decision tree for radius selection
  • Brand-aligned technical precision

v2.0 — Premium Spacing Update (January 2025)

Goal: Create more breathing room for a premium, spacious aesthetic.

Changes:

Token Before After Rationale
--space-20 80px 96px More generous content block padding
--space-section-sm 96px 112px Lighter sections feel less cramped
--space-section-md 120px 144px Standard sections have room to breathe
--space-section-lg 140px 160px Featured sections stand out more
--space-section-xl 160px 184px Hero/CTA sections feel more impactful

Impact:

  • ~15-20% more vertical whitespace across all pages
  • Improved perceived quality and professionalism
  • Better content hierarchy and section separation
  • Maintains 8px grid proportions

v1.0 — Token Migration (January 2025)

Goal: Migrate all hardcoded pixel values to CSS custom properties.

Scope:

  • Converted padding, margin, and gap values to tokens
  • Standardized spacing across 15 landing pages
  • Established token naming conventions

Intentional Exclusions:

  • Button-specific padding (14px 28px)
  • UI mockup elements in hero sections
  • 1px borders and sub-4px values
  • Border-radius and max-width values
  • Media query breakpoints

Session Update — Navbar Standardization & Spacing Fix (January 26, 2026)

Goal: Standardize navigation bar across all pages and fix spacing token issues.

Changes:

  • Standardized navbar CSS across all 15 landing pages using homepage as reference
  • Fixed nav button text color: var(--color-dark-text)var(--color-white)
  • Fixed navbar spacing bug caused by missing legacy token aliases

Spacing Token Fix:

/* Before (broken on pages missing aliases) */
.global-nav_links { gap: var(--space-xl); }
.global-nav_actions { gap: var(--space-lg); }

/* After (works everywhere) */
.global-nav_links { gap: var(--space-8); }  /* 32px */
.global-nav_actions { gap: var(--space-6); }  /* 24px */

Root Cause: Homepage defines legacy aliases (--space-xl: var(--space-8)), but other pages don't. Using numeric tokens directly (--space-8) ensures consistent behavior across all pages.

Best Practice: Prefer numeric space tokens (--space-8, --space-6) over legacy aliases (--space-xl, --space-lg) for cross-page compatibility.


Session Update — Inline Button Padding Token (January 26, 2026)

Goal: Add --btn-padding token directly to all landing page HTML files for self-contained button sizing control.

Added:

  • --btn-padding: 14px 28px token in :root of all 15 landing pages
  • Replaces 44 hardcoded padding: 14px 28px values

Note: This is an inline token (defined in each HTML file's <style> block) rather than a centralized token in tokens.css. This allows each page to be self-contained while still using token-based styling.

Button Classes Updated:

Page Classes
development-feasibility .dfa-btn-primary/secondary/white
rent-roll .rr-btn-primary/secondary/white
api .api-btn-primary/secondary/ghost
query-builder .qb-btn-primary/secondary/ghost
rent-forecast .rf-btn-primary/secondary/white/outline/ghost
market-survey .ms-btn-primary/secondary/ghost/outline
ai-reports .air-btn-primary/secondary, .air-hero-btn-*
market-analytics .ma-btn-primary/secondary/outline
pricing .pricing-btn
our-data .od-btn-primary
about-us .au-btn-primary

Bug Fixed: Circular reference issue where replace_all operation created invalid --btn-padding: var(--btn-padding) definitions in 12 files. Fixed by replacing self-references with correct 14px 28px values.


Quick Reference Card

MICRO (tight groupings)
  --space-1: 4px   │ icon gaps
  --space-2: 8px   │ button icon gap

COMPONENT (internal spacing)
  --space-3: 12px  │ list items, tags
  --space-4: 16px  │ standard padding
  --space-5: 20px  │ comfortable padding
  --space-6: 24px  │ card padding
  --space-8: 32px  │ large padding

LAYOUT (content blocks)
  --space-10: 40px │ medium gaps
  --space-12: 48px │ grid gaps
  --space-14: 56px │ feature padding
  --space-16: 64px │ large gaps
  --space-18: 72px │ mobile sections
  --space-20: 96px │ section internal

SECTION (page rhythm)
  --space-section-sm: 112px │ secondary sections
  --space-section-md: 144px │ standard sections
  --space-section-lg: 160px │ featured sections
  --space-section-xl: 184px │ hero/CTA sections

Related Documentation