From 36a233e08deddf38365313548bb3f9c322015544 Mon Sep 17 00:00:00 2001
From: Grisha <grisha617@gmail.com>
Date: Mon, 27 Apr 2026 23:27:17 -0400
Subject: [PATCH] refactor(styles): split design tokens into base / semantic /
 component layers

---
 .../communities/CommunityCard.astro           |  18 +-
 src/components/content/PostCard.astro         |  16 +-
 src/components/events/EventCard.astro         |   8 +-
 src/components/layout/Footer.astro            |   8 +-
 src/components/layout/Header.astro            |  28 +--
 src/components/layout/Hero.astro              |  14 +-
 src/pages/about.astro                         |   2 +-
 src/pages/communities.astro                   |   4 +-
 src/pages/community-content.astro             |   6 +-
 src/pages/events.astro                        |   6 +-
 src/pages/index.astro                         |   6 +-
 src/styles/global.css                         | 183 ++++++++----------
 src/styles/themes/horizon.css                 |  48 +++++
 src/styles/tokens.base.css                    |  38 ++++
 src/styles/tokens.components.css              |  47 +++++
 src/styles/tokens.semantic.css                | 132 +++++++++++++
 16 files changed, 403 insertions(+), 161 deletions(-)
 create mode 100644 src/styles/themes/horizon.css
 create mode 100644 src/styles/tokens.base.css
 create mode 100644 src/styles/tokens.components.css
 create mode 100644 src/styles/tokens.semantic.css

diff --git a/src/components/communities/CommunityCard.astro b/src/components/communities/CommunityCard.astro
index 9ea7093..b6db392 100644
--- a/src/components/communities/CommunityCard.astro
+++ b/src/components/communities/CommunityCard.astro
@@ -43,8 +43,8 @@ const Tag = href ? "a" : "div";
     display: inline-flex;
     align-items: center;
     gap: var(--space-sm);
-    background: var(--color-surface-card);
-    border: 1px solid var(--color-border);
+    background: var(--card);
+    border: 1px solid var(--card-border);
     border-radius: var(--radius-pill);
     padding: var(--space-xs) var(--space-md) var(--space-xs) var(--space-xs);
     color: inherit;
@@ -53,12 +53,12 @@ const Tag = href ? "a" : "div";
   }
 
   .community-pill--link:hover {
-    border-color: var(--color-primary);
-    background: var(--color-surface-card-hover, var(--color-surface-card));
+    border-color: var(--primary);
+    background: var(--card);
   }
 
   .community-pill--link:focus-visible {
-    outline: 2px solid var(--color-primary);
+    outline: 2px solid var(--primary);
     outline-offset: 2px;
   }
 
@@ -94,23 +94,23 @@ const Tag = href ? "a" : "div";
   .community-pill__name {
     font-size: var(--text-xs);
     font-weight: 600;
-    color: var(--neutral-900);
+    color: var(--card-foreground);
     line-height: 1.2;
     white-space: nowrap;
   }
 
   .community-pill__location {
     font-size: 9px;
-    color: var(--color-text-muted);
+    color: var(--foreground-muted);
     line-height: 1.2;
   }
 
   .community-pill__icon {
     flex-shrink: 0;
-    color: var(--color-primary);
+    color: var(--primary);
     display: flex;
   }
   .community-pill--link:hover .community-pill__icon {
-    color: var(--color-primary-hover);
+    color: var(--primary-hover);
   }
 </style>
diff --git a/src/components/content/PostCard.astro b/src/components/content/PostCard.astro
index d0b52c8..7de83e2 100644
--- a/src/components/content/PostCard.astro
+++ b/src/components/content/PostCard.astro
@@ -51,13 +51,13 @@ const community = `@${source}`;
 
 <style>
   .post-card {
-    background: var(--color-surface-card);
-    border: 1px solid var(--color-border);
+    background: var(--card);
+    border: 1px solid var(--card-border);
     border-radius: var(--radius-md);
     transition: border-color 0.15s ease;
   }
   .post-card:hover {
-    border-color: var(--blue-300);
+    border-color: var(--card-border-hover);
   }
 
   .post-card__link {
@@ -98,13 +98,13 @@ const community = `@${source}`;
     font-family: var(--font-body);
     font-weight: 600;
     font-size: var(--text-sm);
-    color: var(--neutral-900);
+    color: var(--card-foreground);
     line-height: var(--leading-tight);
   }
 
   .post-card__excerpt {
     font-size: var(--text-xs);
-    color: var(--color-text-muted);
+    color: var(--foreground-muted);
     margin-top: var(--space-xs);
     display: -webkit-box;
     -webkit-line-clamp: 2;
@@ -119,16 +119,16 @@ const community = `@${source}`;
     gap: var(--space-sm);
     margin-top: var(--space-sm);
     font-size: var(--text-xs);
-    color: var(--color-text-muted);
+    color: var(--foreground-muted);
   }
 
   .post-card__author {
     font-weight: 500;
-    color: var(--color-text-secondary);
+    color: var(--foreground-secondary);
   }
 
   .post-card__date {
-    color: var(--neutral-400);
+    color: var(--separator-fg);
   }
   .post-card__date::before {
     content: '·';
diff --git a/src/components/events/EventCard.astro b/src/components/events/EventCard.astro
index 7d19d9c..a757027 100644
--- a/src/components/events/EventCard.astro
+++ b/src/components/events/EventCard.astro
@@ -199,13 +199,13 @@ const canRsvp = showRsvp && isLoggedIn && Boolean(cid);
     height: 100%;
   }
   .event-card:hover {
-    border-color: var(--blue-300);
+    border-color: var(--card-border-hover);
   }
 
   .event-card__date {
     font-size: var(--text-sm);
     font-weight: 700;
-    color: var(--color-primary);
+    color: var(--primary);
     text-transform: uppercase;
     letter-spacing: 0.04em;
   }
@@ -213,7 +213,7 @@ const canRsvp = showRsvp && isLoggedIn && Boolean(cid);
   .event-card__name {
     font-family: var(--font-body);
     font-weight: 700;
-    color: var(--neutral-900);
+    color: var(--card-foreground);
     margin-top: var(--space-xs);
     line-height: var(--leading-tight);
     text-wrap: balance;
@@ -241,7 +241,7 @@ const canRsvp = showRsvp && isLoggedIn && Boolean(cid);
 
   .event-card__desc {
     font-size: var(--text-xs);
-    color: var(--color-text-muted);
+    color: var(--foreground-muted);
     margin-top: var(--space-sm);
     display: -webkit-box;
     -webkit-line-clamp: 2;
diff --git a/src/components/layout/Footer.astro b/src/components/layout/Footer.astro
index 065ba44..b754243 100644
--- a/src/components/layout/Footer.astro
+++ b/src/components/layout/Footer.astro
@@ -47,10 +47,10 @@ const year = new Date().getFullYear();
 
 <style>
   .site-footer {
-    border-top: 1px solid var(--color-border);
+    border-top: 1px solid var(--footer-border);
     padding-block: var(--space-2xl);
     margin-top: var(--space-3xl);
-    background: var(--neutral-50);
+    background: var(--footer-bg);
   }
 
   .footer-inner {
@@ -63,7 +63,7 @@ const year = new Date().getFullYear();
 
   .footer-brand {
     font-size: var(--text-xs);
-    color: var(--color-text-muted);
+    color: var(--footer-fg-muted);
   }
 
   .footer-links {
@@ -73,6 +73,6 @@ const year = new Date().getFullYear();
     margin-top: var(--space-xs);
   }
   .footer-links span {
-    color: var(--color-text-muted);
+    color: var(--footer-fg-muted);
   }
 </style>
diff --git a/src/components/layout/Header.astro b/src/components/layout/Header.astro
index 0666c27..38a95c7 100644
--- a/src/components/layout/Header.astro
+++ b/src/components/layout/Header.astro
@@ -50,8 +50,8 @@ const isActive = (href: string) =>
     position: sticky;
     top: 0;
     z-index: 10;
-    background: var(--color-surface-card);
-    border-bottom: 1px solid var(--color-border);
+    background: var(--header-bg);
+    border-bottom: 1px solid var(--header-border);
   }
 
   .site-nav {
@@ -66,7 +66,7 @@ const isActive = (href: string) =>
     align-items: center;
     gap: var(--space-sm);
     text-decoration: none;
-    color: var(--color-primary);
+    color: var(--header-link);
   }
 
   .logo-cloud {
@@ -74,7 +74,7 @@ const isActive = (href: string) =>
     width: 22px;
     height: 12px;
     position: relative;
-    background: var(--blue-200);
+    background: var(--header-link-hover-bg);
     border-radius: 12px;
   }
   .logo-cloud::before {
@@ -83,7 +83,7 @@ const isActive = (href: string) =>
     width: 10px;
     height: 10px;
     border-radius: 50%;
-    background: var(--blue-200);
+    background: var(--header-link-hover-bg);
     top: -5px;
     left: 4px;
   }
@@ -93,7 +93,7 @@ const isActive = (href: string) =>
     width: 7px;
     height: 7px;
     border-radius: 50%;
-    background: var(--blue-200);
+    background: var(--header-link-hover-bg);
     top: -3px;
     left: 12px;
   }
@@ -104,7 +104,7 @@ const isActive = (href: string) =>
     font-size: var(--text-base);
   }
   .logo-at {
-    color: var(--blue-400);
+    color: var(--header-link-inactive);
   }
 
   .nav-links {
@@ -117,15 +117,15 @@ const isActive = (href: string) =>
   .nav-link {
     font-size: var(--text-sm);
     font-weight: 500;
-    color: var(--color-text-muted);
+    color: var(--header-fg-muted);
     text-decoration: none;
     padding-block: var(--space-xs);
   }
   .nav-link:hover {
-    color: var(--color-text);
+    color: var(--header-fg);
   }
   .nav-link--active {
-    color: var(--color-primary);
+    color: var(--header-link);
   }
 
   /* Mobile hamburger */
@@ -140,7 +140,7 @@ const isActive = (href: string) =>
     display: block;
     width: 20px;
     height: 2px;
-    background: var(--color-text);
+    background: var(--header-fg);
     position: relative;
   }
   .hamburger::before,
@@ -149,7 +149,7 @@ const isActive = (href: string) =>
     position: absolute;
     width: 20px;
     height: 2px;
-    background: var(--color-text);
+    background: var(--header-fg);
     left: 0;
   }
   .hamburger::before { top: -6px; }
@@ -171,8 +171,8 @@ const isActive = (href: string) =>
       left: 0;
       right: 0;
       flex-direction: column;
-      background: var(--color-surface-card);
-      border-bottom: 1px solid var(--color-border);
+      background: var(--header-bg);
+      border-bottom: 1px solid var(--header-border);
       padding: var(--space-base) var(--space-lg);
       gap: var(--space-base);
       display: none;
diff --git a/src/components/layout/Hero.astro b/src/components/layout/Hero.astro
index 8e3d75e..aa3c612 100644
--- a/src/components/layout/Hero.astro
+++ b/src/components/layout/Hero.astro
@@ -47,7 +47,7 @@ const { subscriberCount = 1000, groupCount = 10 } = Astro.props;
   .hero {
     position: relative;
     overflow: hidden;
-    background: var(--color-primary);
+    background: var(--primary);
     padding-block: var(--space-3xl) var(--space-3xl);
   }
 
@@ -141,7 +141,7 @@ const { subscriberCount = 1000, groupCount = 10 } = Astro.props;
   }
 
   .hero h1 {
-    color: var(--color-text-on-primary);
+    color: var(--primary-foreground);
     max-width: 28ch;
   }
 
@@ -162,8 +162,8 @@ const { subscriberCount = 1000, groupCount = 10 } = Astro.props;
   }
 
   .btn--hero {
-    background: var(--color-text-on-primary);
-    color: var(--color-primary);
+    background: var(--primary-foreground);
+    color: var(--primary);
     padding: var(--space-md) var(--space-lg);
     border-radius: var(--radius-sm);
     font-family: var(--font-body);
@@ -174,7 +174,7 @@ const { subscriberCount = 1000, groupCount = 10 } = Astro.props;
   }
   .btn--hero:hover {
     opacity: 0.9;
-    color: var(--color-primary);
+    color: var(--primary);
   }
 
   .hero-secondary {
@@ -184,7 +184,7 @@ const { subscriberCount = 1000, groupCount = 10 } = Astro.props;
     text-decoration: none;
   }
   .hero-secondary:hover {
-    color: var(--color-text-on-primary);
+    color: var(--primary-foreground);
   }
 
   .hero-stats {
@@ -200,7 +200,7 @@ const { subscriberCount = 1000, groupCount = 10 } = Astro.props;
     font-family: var(--font-body);
     font-weight: 700;
     font-size: var(--text-xl);
-    color: var(--color-text-on-primary);
+    color: var(--primary-foreground);
   }
 
   .hero-stat__label {
diff --git a/src/pages/about.astro b/src/pages/about.astro
index adf702f..9f36c4c 100644
--- a/src/pages/about.astro
+++ b/src/pages/about.astro
@@ -133,7 +133,7 @@ import Footer from "../components/layout/Footer.astro";
 
     .prose code {
         font-size: 0.9em;
-        background: var(--neutral-100);
+        background: var(--muted);
         padding: 2px 6px;
         border-radius: var(--radius-sm);
     }
diff --git a/src/pages/communities.astro b/src/pages/communities.astro
index 35c574c..ecb91c4 100644
--- a/src/pages/communities.astro
+++ b/src/pages/communities.astro
@@ -60,7 +60,7 @@ const regions = [...grouped.keys()].sort(
   }
 
   .communities-sub {
-    color: var(--color-text-secondary);
+    color: var(--foreground-secondary);
     font-size: var(--text-sm);
     max-width: 55ch;
     line-height: var(--leading-relaxed);
@@ -94,6 +94,6 @@ const regions = [...grouped.keys()].sort(
 
   .community-desc {
     font-size: var(--text-sm);
-    color: var(--color-text-secondary);
+    color: var(--foreground-secondary);
   }
 </style>
diff --git a/src/pages/community-content.astro b/src/pages/community-content.astro
index 0c80732..e3fdc61 100644
--- a/src/pages/community-content.astro
+++ b/src/pages/community-content.astro
@@ -58,7 +58,7 @@ const mergedPosts = (feedResult.entries ?? [])
   }
 
   .content-sub {
-    color: var(--color-text-secondary);
+    color: var(--foreground-secondary);
     font-size: var(--text-sm);
     max-width: 55ch;
     line-height: var(--leading-relaxed);
@@ -75,8 +75,8 @@ const mergedPosts = (feedResult.entries ?? [])
     margin-top: var(--space-xl);
     padding: var(--space-2xl);
     text-align: center;
-    color: var(--color-text-secondary);
-    background: var(--neutral-100);
+    color: var(--foreground-secondary);
+    background: var(--muted);
     border-radius: var(--radius-md);
   }
 </style>
diff --git a/src/pages/events.astro b/src/pages/events.astro
index 0496403..41604b4 100644
--- a/src/pages/events.astro
+++ b/src/pages/events.astro
@@ -109,7 +109,7 @@ const rsvpMessage = Astro.url.searchParams.get('rsvp');
   }
 
   .events-sub {
-    color: var(--color-text-secondary);
+    color: var(--foreground-secondary);
     font-size: var(--text-sm);
     max-width: 55ch;
     line-height: var(--leading-relaxed);
@@ -142,8 +142,8 @@ const rsvpMessage = Astro.url.searchParams.get('rsvp');
     margin-top: var(--space-xl);
     padding: var(--space-2xl);
     text-align: center;
-    color: var(--color-text-secondary);
-    background: var(--neutral-100);
+    color: var(--foreground-secondary);
+    background: var(--muted);
     border-radius: var(--radius-md);
   }
 
diff --git a/src/pages/index.astro b/src/pages/index.astro
index f7eb57f..fe7de47 100644
--- a/src/pages/index.astro
+++ b/src/pages/index.astro
@@ -102,7 +102,7 @@ const events = (eventsResult.entries ?? [])
 
 <style>
   .section--alt {
-    background: var(--neutral-100);
+    background: var(--muted);
   }
 
   .section-header {
@@ -128,8 +128,8 @@ const events = (eventsResult.entries ?? [])
   .empty-state {
     padding: var(--space-xl);
     text-align: center;
-    color: var(--color-text-secondary);
-    background: var(--neutral-100);
+    color: var(--foreground-secondary);
+    background: var(--muted);
     border-radius: var(--radius-md);
     font-size: var(--text-sm);
   }
diff --git a/src/styles/global.css b/src/styles/global.css
index 50a92e5..5505e67 100644
--- a/src/styles/global.css
+++ b/src/styles/global.css
@@ -1,89 +1,40 @@
 /* ============================================
    atmosphere.community — Design System
-   Direction: "Horizon" — warm, breezy, people-forward
+   Default theme: "horizon" - warm, breezy, people-forward
+   Layering:
+     tokens.base       — base tokens, themes redefine here
+     tokens.semantic   — semantic mappings (theme-agnostic)
+     tokens.components — scoped component tokens
+     global            — reset, base elements, components
    ============================================ */
 
-/* --- Fonts --- */
-/* Bitter (display): warm slab serif for headings
-   Source Sans 3 (body): humanist sans for text/UI */
+@import "./tokens.base.css";
+@import "./tokens.semantic.css";
+@import "./tokens.components.css";
 
-/* --- Color Tokens (OKLCH) --- */
+/* --- Structural tokens (NOT themed) --- */
 :root {
-  /* Brand blues — hue ~250 (sky blue family) */
-  --blue-900: oklch(25% 0.08 250);
-  --blue-800: oklch(32% 0.09 250);
-  --blue-700: oklch(48% 0.14 250);
-  --blue-600: oklch(56% 0.13 250);
-  --blue-500: oklch(62% 0.11 250);
-  --blue-400: oklch(68% 0.10 250);
-  --blue-300: oklch(75% 0.08 250);
-  --blue-200: oklch(85% 0.05 250);
-  --blue-100: oklch(90% 0.03 250);
-  --blue-50:  oklch(95% 0.015 250);
-
-  /* Neutrals — tinted toward brand hue 250 */
-  --neutral-900: oklch(22% 0.01 250);
-  --neutral-800: oklch(30% 0.01 250);
-  --neutral-700: oklch(38% 0.01 250);
-  --neutral-600: oklch(48% 0.008 250);
-  --neutral-500: oklch(58% 0.008 250);
-  --neutral-400: oklch(68% 0.006 250);
-  --neutral-300: oklch(78% 0.005 250);
-  --neutral-200: oklch(88% 0.008 250);
-  --neutral-100: oklch(93% 0.008 250);
-  --neutral-50:  oklch(97% 0.005 250);
-
-  /* Accent: teal for communities/events */
-  --teal-600: oklch(55% 0.12 170);
-  --teal-100: oklch(92% 0.03 170);
-
-  /* Accent: coral for warm highlights */
-  --coral-600: oklch(55% 0.14 30);
-  --coral-100: oklch(92% 0.03 30);
-
-  /* Semantic */
-  --color-primary: var(--blue-700);
-  --color-primary-hover: var(--blue-800);
-  --color-text: var(--neutral-900);
-  --color-text-secondary: var(--neutral-600);
-  --color-text-muted: var(--neutral-500);
-  --color-text-on-primary: oklch(98% 0.005 250);
-  --color-surface: oklch(99% 0.004 250);
-  --color-surface-card: oklch(100% 0.002 250);
-  --color-border: var(--neutral-200);
-  --color-link: var(--blue-700);
-  --color-link-hover: var(--blue-800);
-
-  /* Location/status badges */
-  --badge-location-bg: oklch(94% 0.025 145);
-  --badge-location-text: oklch(38% 0.08 145);
-  --badge-online-bg: var(--blue-50);
-  --badge-online-text: var(--blue-700);
-  --badge-tag-bg: var(--blue-50);
-  --badge-tag-text: var(--blue-700);
-
   /* --- Spacing (4pt base) --- */
-  --space-xs:  4px;
-  --space-sm:  8px;
-  --space-md:  12px;
+  --space-xs: 4px;
+  --space-sm: 8px;
+  --space-md: 12px;
   --space-base: 16px;
-  --space-lg:  24px;
-  --space-xl:  32px;
+  --space-lg: 24px;
+  --space-xl: 32px;
   --space-2xl: 48px;
   --space-3xl: 64px;
   --space-4xl: 96px;
 
   /* --- Typography --- */
-  --font-display: 'Bitter', Georgia, serif;
-  --font-body: 'Source Sans 3', 'Source Sans Pro', system-ui, sans-serif;
+  --font-display: "Bitter", Georgia, serif;
+  --font-body: "Source Sans 3", "Source Sans Pro", system-ui, sans-serif;
 
-  /* Type scale — ~1.3 ratio (perfect fourth) */
-  --text-xs:   clamp(0.65rem, 0.6rem + 0.2vw, 0.75rem);
-  --text-sm:   clamp(0.78rem, 0.74rem + 0.2vw, 0.875rem);
+  --text-xs: clamp(0.65rem, 0.6rem + 0.2vw, 0.75rem);
+  --text-sm: clamp(0.78rem, 0.74rem + 0.2vw, 0.875rem);
   --text-base: clamp(0.875rem, 0.84rem + 0.2vw, 1rem);
-  --text-lg:   clamp(1.1rem, 1rem + 0.3vw, 1.25rem);
-  --text-xl:   clamp(1.4rem, 1.2rem + 0.6vw, 1.75rem);
-  --text-2xl:  clamp(1.75rem, 1.4rem + 1vw, 2.25rem);
+  --text-lg: clamp(1.1rem, 1rem + 0.3vw, 1.25rem);
+  --text-xl: clamp(1.4rem, 1.2rem + 0.6vw, 1.75rem);
+  --text-2xl: clamp(1.75rem, 1.4rem + 1vw, 2.25rem);
 
   --leading-tight: 1.2;
   --leading-normal: 1.55;
@@ -114,8 +65,12 @@ html {
 }
 
 @media (prefers-reduced-motion: reduce) {
-  html { scroll-behavior: auto; }
-  *, *::before, *::after {
+  html {
+    scroll-behavior: auto;
+  }
+  *,
+  *::before,
+  *::after {
     animation-duration: 0.01ms !important;
     animation-iteration-count: 1 !important;
     transition-duration: 0.01ms !important;
@@ -126,46 +81,64 @@ body {
   font-family: var(--font-body);
   font-size: var(--text-base);
   line-height: var(--leading-normal);
-  color: var(--color-text);
-  background: var(--color-surface);
+  color: var(--foreground);
+  background: var(--background);
   -webkit-font-smoothing: antialiased;
   -moz-osx-font-smoothing: grayscale;
   min-height: 100dvh;
 }
 
-img, svg {
+img,
+svg {
   display: block;
   max-width: 100%;
   height: auto;
 }
 
 a {
-  color: var(--color-link);
+  color: var(--link);
   text-decoration: none;
   transition: color 0.15s ease;
 }
 a:hover {
-  color: var(--color-link-hover);
+  color: var(--link-hover);
 }
 a:focus-visible {
-  outline: 2px solid var(--color-primary);
+  outline: 2px solid var(--ring);
   outline-offset: 2px;
   border-radius: 2px;
 }
 
-h1, h2, h3, h4 {
+h1,
+h2,
+h3,
+h4 {
   font-family: var(--font-display);
   line-height: var(--leading-tight);
-  color: var(--neutral-900);
+  color: var(--foreground);
   text-wrap: balance;
 }
 
-h1 { font-size: var(--text-2xl); font-weight: 700; }
-h2 { font-size: var(--text-xl);  font-weight: 600; }
-h3 { font-size: var(--text-lg);  font-weight: 600; }
-h4 { font-size: var(--text-base); font-weight: 600; }
+h1 {
+  font-size: var(--text-2xl);
+  font-weight: 700;
+}
+h2 {
+  font-size: var(--text-xl);
+  font-weight: 600;
+}
+h3 {
+  font-size: var(--text-lg);
+  font-weight: 600;
+}
+h4 {
+  font-size: var(--text-base);
+  font-weight: 600;
+}
 
-p + p { margin-top: var(--space-base); }
+p + p {
+  margin-top: var(--space-base);
+}
 
 /* --- Utility Classes --- */
 .container {
@@ -199,8 +172,9 @@ p + p { margin-top: var(--space-base); }
 
 /* --- Card base --- */
 .card {
-  background: var(--color-surface-card);
-  border: 1px solid var(--color-border);
+  background: var(--card);
+  color: var(--card-foreground);
+  border: 1px solid var(--card-border);
   border-radius: var(--radius-md);
   padding: var(--space-base);
 }
@@ -224,17 +198,17 @@ p + p { margin-top: var(--space-base); }
 
 .badge--tag {
   background: var(--badge-tag-bg);
-  color: var(--badge-tag-text);
+  color: var(--badge-tag-fg);
 }
 
 .badge--location {
   background: var(--badge-location-bg);
-  color: var(--badge-location-text);
+  color: var(--badge-location-fg);
 }
 
 .badge--online {
   background: var(--badge-online-bg);
-  color: var(--badge-online-text);
+  color: var(--badge-online-fg);
 }
 
 /* --- Button --- */
@@ -250,27 +224,30 @@ p + p { margin-top: var(--space-base); }
   font-weight: 600;
   line-height: 1;
   cursor: pointer;
-  transition: background 0.15s ease, color 0.15s ease;
+  transition:
+    background 0.15s ease,
+    color 0.15s ease,
+    border-color 0.15s ease;
   text-decoration: none;
 }
 
 .btn--primary {
-  background: var(--color-primary);
-  color: var(--color-text-on-primary);
+  background: var(--btn-primary-bg);
+  color: var(--btn-primary-fg);
 }
 .btn--primary:hover {
-  background: var(--color-primary-hover);
-  color: var(--color-text-on-primary);
+  background: var(--btn-primary-bg-hover);
+  color: var(--btn-primary-fg);
 }
 
 .btn--ghost {
   background: transparent;
-  color: var(--color-primary);
-  border: 1px solid var(--color-border);
+  color: var(--primary);
+  border: 1px solid var(--btn-ghost-border);
 }
 .btn--ghost:hover {
-  background: var(--blue-50);
-  border-color: var(--blue-200);
+  background: var(--btn-ghost-bg-hover);
+  border-color: var(--btn-ghost-border-hover);
 }
 
 .btn--small {
@@ -298,7 +275,7 @@ p + p { margin-top: var(--space-base); }
 }
 
 .section__subtitle {
-  color: var(--color-text-secondary);
+  color: var(--foreground-secondary);
   font-size: var(--text-sm);
   margin-top: var(--space-xs);
 }
@@ -321,8 +298,8 @@ p + p { margin-top: var(--space-base); }
   top: -100%;
   left: var(--space-base);
   padding: var(--space-sm) var(--space-base);
-  background: var(--color-primary);
-  color: var(--color-text-on-primary);
+  background: var(--primary);
+  color: var(--primary-foreground);
   border-radius: var(--radius-sm);
   font-weight: 600;
   z-index: 100;
diff --git a/src/styles/themes/horizon.css b/src/styles/themes/horizon.css
new file mode 100644
index 0000000..9c6be9c
--- /dev/null
+++ b/src/styles/themes/horizon.css
@@ -0,0 +1,48 @@
+/* ============================================
+   Theme: horizon (default)
+   Mood: warm, breezy, people-forward — light mode
+
+   Applied on :root, so it's the default when no
+   [data-theme] attribute is set.
+
+   See tokens.base.css for the rules every theme follows.
+   ============================================ */
+
+:root {
+  /* --- Base tokens (required) --- */
+
+  /* Surface ramp + paired content */
+  --color-base-100: oklch(99% 0.004 250);
+  --color-base-200: oklch(93% 0.008 250);
+  --color-base-300: oklch(88% 0.008 250);
+  --color-base-content: oklch(22% 0.01 250);
+
+  /* Brand pairs */
+  --color-primary: oklch(48% 0.14 250);
+  --color-primary-content: oklch(98% 0.005 250);
+
+  --color-secondary: oklch(62% 0.11 250);
+  --color-secondary-content: oklch(98% 0.005 250);
+
+  --color-accent: oklch(55% 0.14 30);
+  --color-accent-content: oklch(98% 0.005 30);
+
+  --color-neutral: oklch(38% 0.01 250);
+  --color-neutral-content: oklch(97% 0.005 250);
+
+  /* Status pairs */
+  --color-info: oklch(58% 0.12 230);
+  --color-info-content: oklch(98% 0.005 230);
+
+  --color-success: oklch(50% 0.12 145);
+  --color-success-content: oklch(98% 0.005 145);
+
+  --color-warning: oklch(72% 0.15 80);
+  --color-warning-content: oklch(22% 0.05 80);
+
+  --color-error: oklch(55% 0.18 25);
+  --color-error-content: oklch(98% 0.005 25);
+
+  /* --- Component overrides (optional) ---
+     Horizon uses the semantic defaults; nothing to override. */
+}
diff --git a/src/styles/tokens.base.css b/src/styles/tokens.base.css
new file mode 100644
index 0000000..503b724
--- /dev/null
+++ b/src/styles/tokens.base.css
@@ -0,0 +1,38 @@
+/* ============================================
+   Base tokens — the layer themes redefine.
+
+   Each theme lives in its own file under ./themes/.
+   The default theme applies to :root; named themes
+   apply via :root[data-theme="..."] on <html>
+   (the :root prefix bumps specificity so theme overrides
+   beat the :root defaults in tokens.semantic.css and
+   tokens.components.css).
+
+   Rules every theme MUST follow:
+   - Redefine every base token listed below.
+   - Use plain colors only (hex / rgb / oklch).
+     No color-mix(), no var() chains in this layer —
+     keeps it serializable for the future
+     community.atmosphere.theme lexicon.
+   - May also override component tokens
+     (see tokens.components.css) for theme-specific patterns
+     like a header surface that diverges from the page bg.
+   - MUST NOT override the semantic layer.
+
+   Required base tokens:
+     Surfaces:    --color-base-100, --color-base-200,
+                  --color-base-300, --color-base-content
+     Brand:       --color-primary,   --color-primary-content
+                  --color-secondary, --color-secondary-content
+                  --color-accent,    --color-accent-content
+                  --color-neutral,   --color-neutral-content
+     Status:      --color-info / --color-info-content
+                  --color-success / --color-success-content
+                  --color-warning / --color-warning-content
+                  --color-error / --color-error-content
+
+   Components MUST NOT consume base tokens directly —
+   use the semantic or component layer.
+   ============================================ */
+
+@import "./themes/horizon.css";
diff --git a/src/styles/tokens.components.css b/src/styles/tokens.components.css
new file mode 100644
index 0000000..4caff35
--- /dev/null
+++ b/src/styles/tokens.components.css
@@ -0,0 +1,47 @@
+/* ============================================
+   Component / pattern tokens — scoped knobs.
+   Composed from semantic tokens. Add only when a
+   component diverges from a semantic default.
+   ============================================ */
+
+:root {
+  /* Badges */
+  --badge-tag-bg: var(--primary-muted);
+  --badge-tag-fg: var(--primary-muted-foreground);
+
+  --badge-online-bg: var(--primary-muted);
+  --badge-online-fg: var(--primary-muted-foreground);
+
+  --badge-location-bg: var(--success-muted);
+  --badge-location-fg: var(--success-muted-foreground);
+
+  /* Buttons */
+  --btn-primary-bg: var(--primary);
+  --btn-primary-fg: var(--primary-foreground);
+  --btn-primary-bg-hover: var(--primary-hover);
+
+  --btn-ghost-bg-hover: var(--primary-muted);
+  --btn-ghost-border: var(--border);
+  --btn-ghost-border-hover: color-mix(in oklch, var(--primary) 25%, var(--background));
+
+  /* Card */
+  --card-border: var(--border);
+  --card-border-hover: color-mix(in oklch, var(--primary) 35%, var(--background));
+
+  /* Header */
+  --header-bg: var(--card);
+  --header-border: var(--border);
+  --header-fg: var(--foreground);
+  --header-fg-muted: var(--foreground-muted);
+  --header-link: var(--primary);
+  --header-link-hover-bg: color-mix(in oklch, var(--primary) 25%, var(--background));
+  --header-link-inactive: color-mix(in oklch, var(--primary) 50%, var(--background));
+
+  /* Footer */
+  --footer-bg: var(--muted);
+  --footer-border: var(--border);
+  --footer-fg-muted: var(--foreground-muted);
+
+  /* Subtle separator (e.g. dot between meta items) */
+  --separator-fg: var(--foreground-subtle);
+}
diff --git a/src/styles/tokens.semantic.css b/src/styles/tokens.semantic.css
new file mode 100644
index 0000000..582095d
--- /dev/null
+++ b/src/styles/tokens.semantic.css
@@ -0,0 +1,132 @@
+/* ============================================
+   Semantic tokens — theme-agnostic.
+   Composed only from base tokens.
+
+   Rules:
+   - Components consume these by default.
+   - Themes do NOT override this layer.
+   - color-mix() is allowed; raw colors are not.
+   ============================================ */
+
+:root {
+  /* Surfaces */
+  --background: var(--color-base-100);
+  --foreground: var(--color-base-content);
+
+  --card: var(--color-base-100);
+  --card-foreground: var(--color-base-content);
+
+  --popover: var(--color-base-100);
+  --popover-foreground: var(--color-base-content);
+
+  --muted: var(--color-base-200);
+  --muted-foreground: color-mix(
+    in oklch,
+    var(--color-base-content) 65%,
+    var(--color-base-100)
+  );
+
+  /* Foreground variants (layered emphasis) */
+  --foreground-secondary: color-mix(
+    in oklch,
+    var(--color-base-content) 70%,
+    var(--color-base-100)
+  );
+  --foreground-muted: color-mix(
+    in oklch,
+    var(--color-base-content) 55%,
+    var(--color-base-100)
+  );
+  --foreground-subtle: color-mix(
+    in oklch,
+    var(--color-base-content) 30%,
+    var(--color-base-100)
+  );
+
+  /* Borders / interactive */
+  --border: var(--color-base-300);
+  --input: var(--color-base-300);
+  --ring: var(--color-primary);
+
+  /* Brand */
+  --primary: var(--color-primary);
+  --primary-foreground: var(--color-primary-content);
+  --primary-hover: color-mix(
+    in oklch,
+    var(--color-primary) 80%,
+    var(--color-base-content)
+  );
+  --primary-muted: color-mix(
+    in oklch,
+    var(--color-primary) 10%,
+    var(--color-base-100)
+  );
+  --primary-muted-foreground: var(--color-primary);
+
+  --secondary: var(--color-secondary);
+  --secondary-foreground: var(--color-secondary-content);
+
+  --accent: var(--color-accent);
+  --accent-foreground: var(--color-accent-content);
+
+  /* Links */
+  --link: var(--color-primary);
+  --link-hover: color-mix(
+    in oklch,
+    var(--color-primary) 80%,
+    var(--color-base-content)
+  );
+
+  /* Status — solid + muted (muted still signals the state) */
+  --info: var(--color-info);
+  --info-foreground: var(--color-info-content);
+  --info-muted: color-mix(
+    in oklch,
+    var(--color-info) 12%,
+    var(--color-base-100)
+  );
+  --info-muted-foreground: color-mix(
+    in oklch,
+    var(--color-info) 75%,
+    var(--color-base-content)
+  );
+
+  --success: var(--color-success);
+  --success-foreground: var(--color-success-content);
+  --success-muted: color-mix(
+    in oklch,
+    var(--color-success) 14%,
+    var(--color-base-100)
+  );
+  --success-muted-foreground: color-mix(
+    in oklch,
+    var(--color-success) 70%,
+    var(--color-base-content)
+  );
+
+  --warning: var(--color-warning);
+  --warning-foreground: var(--color-warning-content);
+  --warning-muted: color-mix(
+    in oklch,
+    var(--color-warning) 18%,
+    var(--color-base-100)
+  );
+  --warning-muted-foreground: color-mix(
+    in oklch,
+    var(--color-warning) 65%,
+    var(--color-base-content)
+  );
+
+  --error: var(--color-error);
+  --error-foreground: var(--color-error-content);
+  --error-muted: color-mix(
+    in oklch,
+    var(--color-error) 12%,
+    var(--color-base-100)
+  );
+  --error-muted-foreground: color-mix(
+    in oklch,
+    var(--color-error) 70%,
+    var(--color-base-content)
+  );
+}
-- 
2.51.2