Alpha Trait - Design Document

Source of truth for the marketing site UI. Page-specific overrides live in design-system/alpha-trait/pages/. Global baseline rules are in MASTER.md.

Stack: Astro 6 · Tailwind CSS 4 · Plus Jakarta Sans · zinc palette · blue accent

Hierarchy

1. pages/[page].md - overrides for a specific page (e.g. marketing.md for home/marketing)
2. MASTER.md - generated baseline (colors, spacing, anti-patterns)
3. This file (DESIGN.md) - implementation tokens and patterns used in code (src/styles/global.css, section components)

When building UI, prefer tokens and classes documented here over raw values in MASTER.md where they differ (the site uses zinc + #3b82f6, not the older navy palette).

Typography

• Font: Plus Jakarta Sans via --font-jakarta → Tailwind font-sans
• Base: text-sm on body for compact marketing density
• Labels / meta: text-[10px]–text-xs, uppercase tracking on nav badges
• Section titles: .section-title - text-3xl sm:text-4xl, foreground color
• Gradient headlines: .gradient-text - foreground → accent linear gradient

Color tokens

Defined in src/styles/global.css:

Usage

• Zinc neutrals for surfaces, borders, text hierarchy
• Accent blue for primary CTAs, focus rings, active/hover tints
• color-mix(in srgb, var(--accent) N%, …) for subtle washes (8–12% typical)
• Emerald - success / live status (hero badge dot)
• Amber - form errors and warnings only

Dark mode follows prefers-color-scheme: dark on :root.

Core classes

Layout & shape

• Radii: rounded-md (buttons, chips), rounded-xl (cards, hero frame)
• Borders: 1px var(--border), accent mix on hover/focus
• No cyan/neon glow; subtle blue ambient only (grid, orbs, glare)
• Hero grid: items-start gap-6 sm:gap-8 on mobile; tighter vertical rhythm than desktop

Hero

• Media: video on home/about; PNG images on services/solutions/industries (/assets/{category}-{slug}.png)
• Frame: .hero-logo-wrap → .hero-logo-frame with bg-black, overflow-hidden, border + ring
• Mobile (≤1023px): square crop - aspect-ratio: 1, object-fit: cover, object-position: center 46% to trim empty PNG top padding; parallax disabled
• Desktop (≥1024px): natural aspect ratio, max-width: 22rem, scroll parallax on image
• Floating badge: inside card, top-3 right-3
• Floating stat: outside card, -bottom-3 -left-3

Section components

Reusable blocks under src/components/sections/. Content lives in src/data/ (e.g. home.ts, per-page files).

Compose in any Astro page:

---
import Hero from "../components/sections/Hero.astro";
import { hero } from "../data/home";
---
<Hero {...hero} />

Live previews: /design · full demo: /components

Navigation

• Desktop: mega-nav dropdowns with accent-tint panels
• Mobile (≤1023px): hamburger panel; backdrop dim on body; page content blurred (filter: blur(12px)) - logo and menu stay sharp
• Accordion: one section open at a time; all closed by default; reset on menu close

Motion

• Progressive enhancement via public/js/animations.js + html.js-motion-ready
• Scroll reveal: [data-inview], stagger on [data-stagger] > *
• Hero entrance: .hero-animate, .hero-visual
• CSS fallbacks keep content visible without JS
• Respect prefers-reduced-motion: reduce - disable scroll-hide header, parallax, and heavy transitions

Marketing page override

From pages/marketing.md:

• Compact UI, zinc hierarchy, thin borders
• Primary accent #2563eb (light CTAs) / #3b82f6 (tokens & dark)
• Cards use .surface-card; buttons use .btn-primary / .btn-secondary

Anti-patterns

• Emojis as icons - use SVG (Heroicons / Lucide)
• Missing cursor-pointer on clickable elements
• Layout-shifting hover scales
• Low-contrast muted text (maintain 4.5:1)
• Instant state changes - use 150–300ms transitions
• Invisible focus states
• Excessive animation or neon/cyan glow

Checklist

• Tokens from CSS variables, not hard-coded one-offs
• Responsive at 375, 768, 1024, 1440px
• No horizontal scroll on mobile
• Focus-visible rings on interactive elements
• prefers-reduced-motion honored
• Hero PNGs cropped correctly on mobile