AVS Design System
Internal reference for developers & interns. All values render live from CSS custom properties in _root.scss.
1. Brand Colours
The three foundation colours. Everything else is derived from these.
--brand-primary #2563eb (Blue 600) Trust · Education · Knowledge
--brand-secondary #059669 (Green 600) Health · Nature · Growth
--brand-neutral #8b7d6b (Warm Stone) Warm pastel base tone
Rule: Primary Blue = CTAs, links, interactive elements. Secondary Green = success, health-related highlights. Neutral = backgrounds, borders, muted text.
1B. Tailwind Pastel Palette
These tokens live in src/styles/tailwind.css and are used by Tailwind utility classes like bg-pastel-bg, text-pastel-text, etc. They mirror _root.scss values but exist separately for Tailwind compatibility.
--color-pastel-bg #fff6ec Light mode page background
--color-pastel-bg-dark #1e1814 Dark mode page background
--color-pastel-surface #fffdf8 Light mode surface (nav, cards)
--color-pastel-surface-dark #2a2320 Dark mode surface
--color-pastel-text #1a1207 Light mode body text
--color-pastel-text-dark #f0e6dc Dark mode body text
--color-pastel-muted #4b3d2f Light mode muted text
--color-pastel-muted-dark #b8a99a Dark mode muted text
--color-pastel-linen #f5ebe0 Warm linen — cards, alt surfaces
2. Colour Scales
Generated via oklch() from the brand colours. 100 = lightest, 500 = darkest.
Primary Scale
100
200
300
400
500
Secondary Scale
100
200
300
400
500
Neutral Scale
100
200
300
400
500
600
700
800
900
3. Semantic / Status Colours
Use these for UI states — never use raw hex values for success/error/warning/info.
--color-success
--color-success-muted
✅ Form success, positive indicators, health tips
--color-warning
--color-warning-muted
⚠️ Caution notices, health warnings, disclaimers
--color-error
--color-error-muted
❌ Form errors, validation failures, critical alerts
--color-info
--color-info-muted
ℹ️ Informational badges, tips, help text
4. Surface & Background Colours
Used for section backgrounds across the homepage (12-section rhythm: L→D→G→L→W→T).
--background-color Page default (#fff6ec / #1e1814)
--background-color-alt Ivory / Dark cocoa (#fffdf8 / #2a2320)
--surface-warm Voices, Work In Action
--surface-tinted Impact Dashboard (#f5ebe0)
--surface-grey Trust Signals (#f5efe8)
--surface-dark Crisis, Knowledge Hub (deep navy)
4B. Homepage Section Colour Map
Each homepage section has its own colour theme. These are NOT centralized tokens — they are hardcoded oklch() values inside each component's <style> block.
| Section | Background | Text Colour | Accent | Source File |
|---|---|---|---|---|
| Hero | Page default | var(--foreground-color) | Brand primary | Hero.astro |
| Crisis | Near-black navy | Near-white | Amber, Crimson, Teal, Orange | Crisis.astro |
| Impact Dashboard | var(--surface-tinted) | var(--foreground-color) | Brand primary | ImpactDashboard.astro |
| Programs | var(--surface-warm) | var(--foreground-color) | Brand secondary | Programs.astro |
| Credibility | var(--surface-grey) | var(--foreground-color) | Per-badge accent colours | Credibility.astro |
| Voices | var(--surface-warm) | var(--foreground-color) | var(--accent-warm) | Voices.astro |
| Work In Action | var(--surface-warm) | var(--foreground-color) | Brand secondary | WorkInAction.astro |
| Funding Goals | Near-white warm | Muted dark | Green, Blue gradients | FundingGoals.astro |
| Newsletter | Brand primary gradient | White | White / semi-transparent white | Newsletter.astro |
| CTA Banner | Brand gradient (Primary → Secondary) | White | White | CTABanner.astro |
| Gallery | Image backgrounds | White on dark overlays | var(--brand-primary), var(--brand-secondary) | GalleryGrid.astro |
| Photo Carousel | Image backgrounds | White captions | var(--brand-primary) dots | PhotoCarousel.astro |
| Inline CTA | oklch warm or cool tints | Warm accent, Cool accent | Per-variant | InlineCTA.astro |
4C. Component-Specific Colours ⚠️
WARNING FOR INTERNS: This project has 300+ hardcoded
oklch() colour values scattered across 15+ section components. These are NOT in _root.scss or Tailwind. They live INSIDE each component's <style> block.Components with hardcoded colours
| Component | Approx. inline colours | Why? |
|---|---|---|
Crisis.astro | ~40 | Dark section with custom accent colours per stat card |
FundingGoals.astro | ~35 | Green/blue theme cards with gradients and hover states |
Credibility.astro | ~30 | Trust badges with unique brand colours per partner |
Voices.astro | ~25 | Quote cards, attribution styles, wisdom verse styling |
ImpactDashboard.astro | ~20 | Counter cards, progress bars, stat labels |
Programs.astro | ~20 | Program cards with category colour coding |
Newsletter.astro | ~15 | Success/error states, hover effects |
WorkInAction.astro | ~15 | Photo cards, overlay colours |
InlineCTA.astro | ~15 | Warm/cool variant tints |
TeamPreview.astro | ~10 | Card hover, role badge colours |
CTABanner.astro | ~10 | Gradient backgrounds |
Manifesto.astro | ~10 | Sanskrit verse styling on dark |
SupportOptions.astro | ~10 | Donation card styling |
UPIDonation.astro | ~10 | UPI payment card colours |
GalleryGrid.astro | ~5 | Overlay, category filter buttons |
What this means for you
✅ When modifying a section
- Open the component file FIRST
- Read its
<style>block to understand its colour palette - Match new colours to existing oklch hue angles in that component
- Test both light AND dark mode — most use
light-dark()
❌ Common mistakes
- Don't assume
_root.scsstokens cover everything - Don't add new hex colours — use
oklch()to match existing sections - Don't copy colours from one section to another without checking hue angles
- Don't forget
light-dark()— EVERY colour needs light + dark variants
oklch() cheat sheet:
oklch(lightness% chroma hue) — Lightness: 0% (black) → 100% (white). Chroma: 0 (grey) → 0.4 (vivid). Hue: 0 (pink) → 75 (amber) → 150 (green) → 230 (blue) → 330 (magenta) → 360 (pink again).5. Typography
Three languages need different font stacks. html[lang] switches fonts automatically.
English — Headings
Atkinson Hyperlegible
--font-heading-enDesigned for maximum legibility. Used for all headings in English pages.
English — Body
Lexend — optimised for reading fluency and accessibility
--font-body-enUsed for paragraphs, lists, captions, and UI labels in English.
Hindi / Sanskrit — Headings
नोटो सांस देवनागरी
--font-heading-hiNoto Sans Devanagari — clear conjuncts, even weight distribution.
Hindi / Sanskrit — Body
मुक्ता — स्वास्थ्य शिक्षा के लिए पठनीय देवनागरी
--font-body-hiMukta — readable Devanagari for long-form health content. Uses --leading-devanagari: 1.7 line-height.
Line Height Tokens
| Token | Value | Use |
|---|---|---|
--leading-tight | 1.2 | Display text, headings |
--leading-snug | 1.375 | Large headings |
--leading-normal | 1.5 | English body text |
--leading-relaxed | 1.625 | Long-form content |
--leading-devanagari | 1.7 | Hindi & Sanskrit text (taller glyphs need more space) |
6. Type Scale (Utopia Fluid)
All sizes use clamp() — they're fluid between 320px and 1240px viewport. Utopia calculator ↗
--text-xs The quick brown fox — footnotes, labels ~11px--text-sm The quick brown fox — captions, meta text ~14px--text-base The quick brown fox — body text ~16-18px--text-lg The quick brown fox — card titles ~20-22px--text-xl The quick brown fox — section subtitles ~23-28px--text-2xl The quick brown fox — section headings ~28-35px--text-3xl The quick brown fox — page headings ~33-44px--text-4xl Hero subtitles ~40-55px--text-5xl Hero titles ~48-69px7. Spacing Scale (Utopia Fluid)
All spacing is fluid — grows between 320px and 1240px viewport. Use these instead of hardcoded pixel values. Utopia calculator ↗
--space-3xs~4-5px--space-2xs~8-9px--space-xs~12-14px--space-s~16-18px--space-m~24-27px--space-l~32-36px--space-xl~48-54px--space-2xl~64-72px--space-3xl~96-108pxRule: Always use spacing tokens for
margin, padding, and gap. Never write padding: 20px — write padding: var(--space-s).8. Border Radius
--radius-xs 2px Inline elements--radius-s 4px Badges, tags--radius-m 8px Buttons, inputs--radius-l 12px Medium elements--radius-h 16px Large cards, hero--radius-xl 32px Extra large cards--radius-full 9999px Pill / circles9. Elevations / Shadows
Higher number = more depth. Cards use special --elevation-card and --elevation-card-hover.
--elevation-1
--elevation-2
--elevation-3
--elevation-4
--elevation-5
--elevation-card
--elevation-card-hover
10. Z-Index Layers
Always use these tokens — never write z-index: 9999.
| Token | Value | Typical use |
|---|---|---|
--z-index--1 | -1 | Behind everything (decorative pseudo-elements) |
--z-index-0 | 0 | Default layer |
--z-index-1 | 10 | Slight elevation (sticky elements) |
--z-index-2 | 20 | Dropdowns, tooltips |
--z-index-3 | 30 | Fixed header |
--z-index-5 | 50 | Mobile menu overlay |
--z-index-8 | 80 | Modal backdrop |
--z-index-9 | 90 | Modal content |
--z-index-10 | 100 | Cookie banner, critical alerts |
11. Animations & Easing
--ease-premium Snappy arrival, smooth settle. Default for interactions.--ease-smooth Material Design standard. Page transitions.--cubic-bezier General-purpose easing curve.Speed Tokens
| Token | Duration | Use |
|---|---|---|
--animation-speed-instant | 0.1s | Micro-interactions (active states) |
--animation-speed-fast | 0.2s | Hover effects, tooltips |
--animation-speed-medium | 0.3s | Dropdowns, disclosure widgets |
--animation-speed-slow | 0.4s | Page transitions, modal reveals |
12. Button Variants
All buttons match WCAG AA contrast (4.5:1 minimum). Token format: --color-[variant]-[bg | border | text].
13. Aspect Ratios
1:1
--ratio-square Avatars, icons4:3
--ratio-landscape Photos, cards3:4
--ratio-portrait Portrait photos16:9
--ratio-widescreen Videos, hero images18:5
--ratio-ultrawide Banner imagesQuick Reference for Interns
✅ DO
- Use
var(--space-s)for spacing - Use
var(--text-lg)for font sizes - Use
var(--brand-primary)for brand colours - Use
var(--radius-m)for border radius - Use
var(--elevation-2)for shadows - Use
var(--ease-premium)for transition timing - Test in both light AND dark mode
- Test in English AND Hindi
❌ DON'T
- Don't write
margin: 20px— use tokens - Don't write
color: #2563eb— usevar(--brand-primary) - Don't write
font-size: 18px— usevar(--text-base) - Don't write
z-index: 9999— use z-index tokens - Don't write raw
border-radius: 8px— usevar(--radius-m) - Don't use
font-family:directly — usevar(--font-body) - Don't add new colours without checking this page first
📁 Key Files
| File | What it contains |
|---|---|
src/assets/scss/base/_root.scss | ALL design tokens (colours, type, spacing, etc.) |
src/assets/scss/base/_font.scss | @font-face declarations (9 fonts) |
src/assets/scss/base/_reset.scss | CSS reset / normalise |
src/styles/skeleton.css | Loading skeleton shimmer utilities |
src/styles/tailwind.css | Tailwind utilities (minimal — most styles are vanilla CSS) |
src/i18n/en.json | English UI strings (870 lines) |
src/i18n/hi.json | Hindi UI strings |
src/i18n/sa.json | Sanskrit UI strings |