DESIGN.md — adscalculator.xyz

Single source of truth for visual design decisions. OWL (design profile), developer, and any agent doing UI work MUST read this before writing CSS/HTML. Keep in sync with style/tokens.css — if you change tokens in code, update this file in the same commit.

Brand Personality

Professional fintech-tool aesthetic: trustworthy, precise, calm. Dark-first (default), light theme available via [data-theme="light"].

Color Tokens

Dark Theme (default — `:root`)

Token	Value	Usage
`--primary-color`	`#64ffda`	Accent: CTAs, links, highlights
`--background-color`	`#0a192f`	Page background (deep navy)
`--card-background`	`#172a45`	Cards, panels
`--text-color`	`#ccd6f6`	Body text
`--label-color`	`#a0aac0`	Labels, secondary text
`--border-color`	`#233554`	Card/input borders
`--shadow`	`0 4px 12px rgba(0,0,0,.2)`	Cards
`--green-color`	`#2ecc71`	Positive results
`--red-color`	`#e74c3c`	Negative results

Light Theme (`[data-theme="light"]`)

Token	Value
`--primary-color`	`#077A7D`
`--background-color`	`#F5EEDD`
`--card-background`	`#FCF9EC`
`--text-color`	`#333333`

⚠️ Never hardcode hex values — always reference tokens.

Typography

Font: Outfit (self-hosted WOFF2, weights 700 + 800, font-display: swap)
Body/base sizes use rem; headings scale up to ~2rem
Fallback stack: system sans-serif

Layout System

Sticky nav height: --sticky-nav-height: 61px
Spacing: rem-based (0.75 / 1 / 1.5 / 2rem steps)
Cards: Bento Grid pattern (cards.css, simple-grid.css)
Calculator cards share card-headers.css patterns

Component Patterns

Pattern	File
Calculator cards	`style/cards.css` + `card-headers.css`
Results display	`style/results.css`
Blog grid/list	`style/blog-*.css`
Modals	`style/modals.css`
Buttons	`style/buttons.css`

CSS Architecture Rules

26 modules concatenated → style/style.css at build. NEVER edit dist/.
New styles go in the correct existing module; new module only for a genuinely new concern.
No inline styles when a token/class exists.
Theme switcher: js/theme-switcher.js — both themes must stay visually complete.

Quality Bar (before commit)

Both themes checked (dark default + light)
Responsive: mobile-first, verify 375px → desktop
WCAG AA contrast on new color pairs
Core Web Vitals: no layout shift from new elements

DESIGN.md — adscalculator.xyz

Brand Personality

Color Tokens

Dark Theme (default — :root)

Light Theme ([data-theme="light"])

Typography

Layout System

Component Patterns

CSS Architecture Rules

Quality Bar (before commit)

Dark Theme (default — `:root`)

Light Theme (`[data-theme="light"]`)