From 0fe1e066456a07b0743cb233842fde958f1951ae Mon Sep 17 00:00:00 2001
From: Guillem Arias Fauste <gariasf@proton.me>
Date: Mon, 4 May 2026 00:50:52 +0200
Subject: [PATCH] refactor(design-system): migrate fg-* utilities to text-* and
 remove namespace (#1626)

* refactor(design-system): migrate fg-* utilities to text-* and remove namespace

The design system carried two parallel namespaces for foreground colors:
text-* (canonical, ~2,000 uses) and fg-* (32 uses). Most fg-* tokens
were 1:1 duplicates of a text-* counterpart. fg-gray was nearly
identical to text-secondary, with a one-step shade difference in dark
mode.

This PR migrates all 32 usages to their text-* equivalents and removes
the fg-* block from the design tokens. Closes #1606.

Mapping:
- fg-inverse  -> text-inverse  (20 usages, identical light/dark values)
- fg-gray     -> text-secondary (7 usages; light values match, dark is
                                 one step lighter: gray-300 vs gray-400)
- fg-primary  -> text-primary  (3 usages, identical values)
- fg-subdued  -> text-subdued  (2 usages, identical values)

The four other fg-* tokens (fg-contrast, fg-primary-variant,
fg-secondary, fg-secondary-variant) had zero usages despite being
defined; they are removed without replacement.

JSON / build:
- design/tokens/sure.tokens.json: $version 1.0.0 -> 2.0.0 (breaking
  schema change per the policy added in #1620). 8 fg-* token
  definitions removed.
- button-bg-ghost-hover's dark value still references "fg-inverse"
  internally; rewritten to "bg-gray-800 text-inverse" so the cleanup
  doesn't break that utility.
- _generated.css regenerated. 42 utility blocks now (was 50).

Lookbook tokens preview:
- The Text & foregrounds section dropped its split between text-*
  (canonical) and fg-* (legacy). Now a single section listing the
  five text-* utilities. The "(legacy)" framing is gone since there's
  no legacy left.

README:
- design/tokens/README.md's button-bg-ghost-hover edge-case example
  updated to reflect the new "bg-gray-800 text-inverse" dark value.

Visual review needed in dark mode:
- Anywhere icons use the application_helper#icon helper with
  color: "default" (most icons in the app). The default class moved
  from fg-gray (gray-400 dark) to text-secondary (gray-300 dark), so
  default-color icons render slightly lighter in dark mode.
- DS::Buttonish icons in secondary buttons (same shade shift).
- DS::Link icons (same).
- Time series chart axes (same).
- All tooltips, account add flow, settings hostings buttons,
  invitations, AI consent, family export, danger-zone buttons --
  these used fg-inverse, which is identical to text-inverse, so no
  visual change expected.

* fix(design-system): use inverse pair on tooltips for readable dark mode

* fix(lookbook): use semantic tokens in menu preview header text

* fix(lookbook): set text-primary on layout body so previews inherit theme

* fix(design-system): keep shadows dark-toned in dark mode

Inverting shadows to white|8% on dark surfaces produces a halo
effect rather than an elevation cue, and stacks redundantly with
the alpha-white 1px ring already in shadow-border-*.

Switch dark-mode shadows to black at progressively higher alpha
(25%/30%/35%/40%/50% for xs..xl) so they read as actual cast
shadows on near-black surfaces. Surface-tint differences and the
existing alpha-white border ring continue to handle elevation
hierarchy and edge definition.

Approach matches Material 3, Apple HIG, IBM Carbon, Refactoring UI,
and the dark-mode shadows used in Linear/Vercel/Stripe.

* fix(design-system): set text-primary on DS::Dialog element

Browser UA stylesheets apply color: black directly to <dialog>,
which overrides ancestor inheritance even when a body or html
ancestor sets a theme-aware color. Unstyled child content then
renders black regardless of theme.

Setting text-primary on the dialog element itself defeats the UA
override and lets descendants inherit the semantic token.

* fix(lookbook): use shadow css vars in effects preview so dark theme renders

* Revert "fix(design-system): keep shadows dark-toned in dark mode"

This reverts commit 3e9d76ed0beb5ac5f2acbad61e4d1c39eadc9ac2.

* fix(design-system): use opacity-70 instead of text-inverse/70 in value tooltip

The custom @utility text-inverse expands to @apply text-white and
isn't modifier-aware, so text-inverse/70 produced no CSS at all and
the muted labels fell through to inherited color (invisible on the
white pill in dark mode).

Replace with text-inverse + opacity-70. Same visual effect, works
with the existing utility definition.
---
 .../sure-design-system/_generated.css         | 74 +++----------------
 app/components/DS/buttonish.rb                | 14 ++--
 app/components/DS/dialog.html.erb             |  2 +-
 app/components/DS/link.rb                     |  2 +-
 app/components/DS/tooltip.html.erb            |  4 +-
 app/helpers/application_helper.rb             |  2 +-
 .../time_series_chart_controller.js           |  6 +-
 app/views/accounts/_account_type.html.erb     |  2 +-
 app/views/accounts/new.html.erb               |  2 +-
 app/views/chats/_ai_consent.html.erb          |  2 +-
 app/views/family_exports/new.html.erb         |  2 +-
 .../holdings/_missing_price_tooltip.html.erb  |  4 +-
 app/views/investments/_value_tooltip.html.erb | 18 ++---
 app/views/invitations/new.html.erb            |  2 +-
 app/views/layouts/lookbooks.html.erb          |  2 +-
 app/views/pages/changelog.html.erb            |  2 +-
 .../hostings/_assistant_settings.html.erb     |  4 +-
 .../hostings/_danger_zone_settings.html.erb   |  4 +-
 app/views/settings/profiles/show.html.erb     |  2 +-
 app/views/shared/_money_field.html.erb        |  2 +-
 app/views/shared/_text_tooltip.erb            |  4 +-
 app/views/shared/notifications/_cta.html.erb  |  2 +-
 design/tokens/README.md                       |  2 +-
 design/tokens/sure.tokens.json                | 14 +---
 .../previews/design_tokens_preview.rb         |  5 +-
 .../design_tokens_preview/effects.html.erb    |  2 +-
 .../design_tokens_preview/text.html.erb       | 71 ++++++------------
 .../previews/menu_component_preview.rb        |  6 +-
 28 files changed, 83 insertions(+), 175 deletions(-)

diff --git a/app/assets/tailwind/sure-design-system/_generated.css b/app/assets/tailwind/sure-design-system/_generated.css
index bb473b187..dc4e8f855 100644
--- a/app/assets/tailwind/sure-design-system/_generated.css
+++ b/app/assets/tailwind/sure-design-system/_generated.css
@@ -302,70 +302,6 @@
   @apply bg-surface-inset animate-pulse;
 }
 
-@utility fg-gray {
-  @apply text-gray-500;
-
-  @variant theme-dark {
-    @apply text-gray-400;
-  }
-}
-
-@utility fg-contrast {
-  @apply text-gray-400;
-
-  @variant theme-dark {
-    @apply text-gray-500;
-  }
-}
-
-@utility fg-inverse {
-  @apply text-white;
-
-  @variant theme-dark {
-    @apply text-gray-900;
-  }
-}
-
-@utility fg-primary {
-  @apply text-gray-900;
-
-  @variant theme-dark {
-    @apply text-white;
-  }
-}
-
-@utility fg-primary-variant {
-  @apply text-gray-800;
-
-  @variant theme-dark {
-    @apply text-gray-50;
-  }
-}
-
-@utility fg-secondary {
-  @apply text-gray-50;
-
-  @variant theme-dark {
-    @apply text-gray-400;
-  }
-}
-
-@utility fg-secondary-variant {
-  @apply text-gray-100;
-
-  @variant theme-dark {
-    @apply text-gray-500;
-  }
-}
-
-@utility fg-subdued {
-  @apply text-gray-400;
-
-  @variant theme-dark {
-    @apply text-gray-500;
-  }
-}
-
 @utility text-primary {
   @apply text-gray-900;
 
@@ -498,6 +434,14 @@
   }
 }
 
+@utility border-inverse {
+  @apply border-alpha-white-200;
+
+  @variant theme-dark {
+    @apply border-alpha-black-300;
+  }
+}
+
 @utility button-bg-primary {
   @apply bg-gray-900;
 
@@ -558,7 +502,7 @@
   @apply bg-gray-50;
 
   @variant theme-dark {
-    @apply bg-gray-800 fg-inverse;
+    @apply bg-gray-800 text-inverse;
   }
 }
 
diff --git a/app/components/DS/buttonish.rb b/app/components/DS/buttonish.rb
index 0c68d1dbe..e85169191 100644
--- a/app/components/DS/buttonish.rb
+++ b/app/components/DS/buttonish.rb
@@ -2,11 +2,11 @@ class DS::Buttonish < DesignSystemComponent
   VARIANTS = {
     primary: {
       container_classes: "text-inverse bg-inverse hover:bg-inverse-hover disabled:bg-gray-500 theme-dark:disabled:bg-gray-400",
-      icon_classes: "fg-inverse"
+      icon_classes: "text-inverse"
     },
     secondary: {
       container_classes: "text-primary bg-gray-200 theme-dark:bg-gray-700 hover:bg-gray-300 theme-dark:hover:bg-gray-600 disabled:bg-gray-200 theme-dark:disabled:bg-gray-600",
-      icon_classes: "fg-primary"
+      icon_classes: "text-primary"
     },
     destructive: {
       container_classes: "text-inverse bg-red-500 theme-dark:bg-red-400 hover:bg-red-600 theme-dark:hover:bg-red-500 disabled:bg-red-200 theme-dark:disabled:bg-red-600",
@@ -14,23 +14,23 @@ class DS::Buttonish < DesignSystemComponent
     },
     outline: {
       container_classes: "text-primary border border-secondary bg-transparent hover:bg-surface-hover",
-      icon_classes: "fg-gray"
+      icon_classes: "text-secondary"
     },
     outline_destructive: {
       container_classes: "text-destructive border border-secondary bg-transparent hover:bg-gray-100 theme-dark:hover:bg-gray-700",
-      icon_classes: "fg-gray"
+      icon_classes: "text-secondary"
     },
     ghost: {
       container_classes: "text-primary bg-transparent hover:bg-gray-100 theme-dark:hover:bg-gray-700",
-      icon_classes: "fg-gray"
+      icon_classes: "text-secondary"
     },
     icon: {
       container_classes: "hover:bg-gray-100 theme-dark:hover:bg-gray-700",
-      icon_classes: "fg-gray"
+      icon_classes: "text-secondary"
     },
     icon_inverse: {
       container_classes: "bg-inverse hover:bg-inverse-hover",
-      icon_classes: "fg-inverse"
+      icon_classes: "text-inverse"
     }
   }.freeze
 
diff --git a/app/components/DS/dialog.html.erb b/app/components/DS/dialog.html.erb
index 307303970..e6892b1ce 100644
--- a/app/components/DS/dialog.html.erb
+++ b/app/components/DS/dialog.html.erb
@@ -1,5 +1,5 @@
 <%= wrapper_element do %>
-  <%= tag.dialog class: "w-full h-full bg-transparent theme-dark:backdrop:bg-alpha-black-900 backdrop:bg-overlay pt-[env(safe-area-inset-top)] pb-[env(safe-area-inset-bottom)] #{(drawer? || responsive?) ? "lg:p-3" : "lg:p-1"}", **merged_opts do %>
+  <%= tag.dialog class: "w-full h-full bg-transparent text-primary theme-dark:backdrop:bg-alpha-black-900 backdrop:bg-overlay pt-[env(safe-area-inset-top)] pb-[env(safe-area-inset-bottom)] #{(drawer? || responsive?) ? "lg:p-3" : "lg:p-1"}", **merged_opts do %>
     <%= tag.div class: dialog_outer_classes do %>
       <%= tag.div class: dialog_inner_classes, data: { DS__dialog_target: "content" } do %>
         <div class="grow py-4 space-y-4 flex flex-col <%= "overflow-auto" if scrollable %>">
diff --git a/app/components/DS/link.rb b/app/components/DS/link.rb
index 209f86b09..41ea3f3f2 100644
--- a/app/components/DS/link.rb
+++ b/app/components/DS/link.rb
@@ -6,7 +6,7 @@ class DS::Link < DS::Buttonish
   VARIANTS = VARIANTS.reverse_merge(
     default: {
       container_classes: "",
-      icon_classes: "fg-gray"
+      icon_classes: "text-secondary"
     }
   ).freeze
 
diff --git a/app/components/DS/tooltip.html.erb b/app/components/DS/tooltip.html.erb
index 3bd7a1ba1..a10c1147f 100644
--- a/app/components/DS/tooltip.html.erb
+++ b/app/components/DS/tooltip.html.erb
@@ -1,8 +1,8 @@
 <span data-controller="DS--tooltip" data-DS--tooltip-placement-value="<%= placement %>" data-DS--tooltip-offset-value="<%= offset %>" data-DS--tooltip-cross-axis-value="<%= cross_axis %>" class="inline-flex">
   <%= helpers.icon icon_name, size: size, color: color %>
 
-  <div role="tooltip" data-DS--tooltip-target="tooltip" class="hidden absolute z-50 bg-gray-700 text-sm px-1.5 py-1 rounded-md">
-    <div class="fg-inverse font-normal max-w-[200px]">
+  <div role="tooltip" data-DS--tooltip-target="tooltip" class="hidden absolute z-50 bg-inverse text-sm px-1.5 py-1 rounded-md">
+    <div class="text-inverse font-normal max-w-[200px]">
       <%= tooltip_content %>
     </div>
   </div>
diff --git a/app/helpers/application_helper.rb b/app/helpers/application_helper.rb
index e8a7f008b..4793b2303 100644
--- a/app/helpers/application_helper.rb
+++ b/app/helpers/application_helper.rb
@@ -17,7 +17,7 @@ module ApplicationHelper
   def icon(key, size: "md", color: "default", custom: false, as_button: false, **opts)
     extra_classes = opts.delete(:class)
     sizes = { xs: "w-3 h-3", sm: "w-4 h-4", md: "w-5 h-5", lg: "w-6 h-6", xl: "w-7 h-7", "2xl": "w-8 h-8" }
-    colors = { default: "fg-gray", white: "fg-inverse", success: "text-success", warning: "text-warning", destructive: "text-destructive", current: "text-current" }
+    colors = { default: "text-secondary", white: "text-inverse", success: "text-success", warning: "text-warning", destructive: "text-destructive", current: "text-current" }
 
     icon_classes = class_names(
       "shrink-0",
diff --git a/app/javascript/controllers/time_series_chart_controller.js b/app/javascript/controllers/time_series_chart_controller.js
index 4344bf59a..98baffc17 100644
--- a/app/javascript/controllers/time_series_chart_controller.js
+++ b/app/javascript/controllers/time_series_chart_controller.js
@@ -110,7 +110,7 @@ export default class extends Controller {
       .attr("cx", this._d3InitialContainerWidth / 2)
       .attr("cy", this._d3InitialContainerHeight / 2)
       .attr("r", 4)
-      .attr("class", "fg-subdued")
+      .attr("class", "text-subdued")
       .style("fill", "currentColor");
   }
 
@@ -220,7 +220,7 @@ export default class extends Controller {
     // Style ticks
     this._d3Group
       .selectAll(".tick text")
-      .attr("class", "fg-gray")
+      .attr("class", "text-secondary")
       .style("font-size", "12px")
       .style("font-weight", "500")
       .attr("text-anchor", "middle")
@@ -334,7 +334,7 @@ export default class extends Controller {
         // Guideline
         this._d3Group
           .append("line")
-          .attr("class", "guideline fg-subdued")
+          .attr("class", "guideline text-subdued")
           .attr("x1", this._d3XScale(d.date))
           .attr("y1", 0)
           .attr("x2", this._d3XScale(d.date))
diff --git a/app/views/accounts/_account_type.html.erb b/app/views/accounts/_account_type.html.erb
index 741ace78b..3605e48b4 100644
--- a/app/views/accounts/_account_type.html.erb
+++ b/app/views/accounts/_account_type.html.erb
@@ -1,7 +1,7 @@
 <%# locals: (accountable:) %>
 
 <%= link_to new_polymorphic_path(accountable, step: "method_select", return_to: params[:return_to]),
-            class: "flex items-center gap-4 w-full text-center focus:outline-hidden hover:bg-surface-hover focus:bg-surface-hover fg-primary border border-transparent block px-2 rounded-lg p-2" do %>
+            class: "flex items-center gap-4 w-full text-center focus:outline-hidden hover:bg-surface-hover focus:bg-surface-hover text-primary border border-transparent block px-2 rounded-lg p-2" do %>
   <%= render DS::FilledIcon.new(
     icon: accountable.icon,
     hex_color: accountable.color,
diff --git a/app/views/accounts/new.html.erb b/app/views/accounts/new.html.erb
index 01b02a575..7caa4dda3 100644
--- a/app/views/accounts/new.html.erb
+++ b/app/views/accounts/new.html.erb
@@ -27,7 +27,7 @@
     <% unless params[:return_to].present? %>
       <%= button_to imports_path(import: { type: "AccountImport" }),
               data: { turbo_frame: :_top },
-            class: "flex items-center gap-4 w-full text-center focus:outline-hidden hover:bg-surface-hover focus:bg-surface-hover fg-primary border border-transparent block px-2 rounded-lg p-2" do %>
+            class: "flex items-center gap-4 w-full text-center focus:outline-hidden hover:bg-surface-hover focus:bg-surface-hover text-primary border border-transparent block px-2 rounded-lg p-2" do %>
         <%= render DS::FilledIcon.new(
           icon: "download",
           hex_color: "#F79009",
diff --git a/app/views/chats/_ai_consent.html.erb b/app/views/chats/_ai_consent.html.erb
index 3e9437508..305847922 100644
--- a/app/views/chats/_ai_consent.html.erb
+++ b/app/views/chats/_ai_consent.html.erb
@@ -18,7 +18,7 @@
     <%= form_with url: user_path(Current.user), method: :patch, class: "w-full", data: { turbo: false } do |form| %>
       <%= form.hidden_field "user[ai_enabled]", value: true %>
       <%= form.hidden_field "user[redirect_to]", value: "home" %>
-      <%= form.submit "Enable AI Chats", class: "cursor-pointer hover:bg-inverse-hover w-full py-2 px-4 bg-inverse fg-inverse rounded-lg text-sm font-medium" %>
+      <%= form.submit "Enable AI Chats", class: "cursor-pointer hover:bg-inverse-hover w-full py-2 px-4 bg-inverse text-inverse rounded-lg text-sm font-medium" %>
     <% end %>
   <% end %>
 
diff --git a/app/views/family_exports/new.html.erb b/app/views/family_exports/new.html.erb
index 7c8f3ac98..d6942158b 100644
--- a/app/views/family_exports/new.html.erb
+++ b/app/views/family_exports/new.html.erb
@@ -34,7 +34,7 @@
       <%= form_with url: family_exports_path, method: :post, class: "space-y-4" do |form| %>
         <div class="flex gap-3">
           <%= link_to "Cancel", "#", class: "flex-1 text-center px-4 py-2 text-primary bg-surface border border-primary rounded-lg hover:bg-surface-hover", data: { action: "click->modal#close" } %>
-          <%= form.submit "Export data", class: "flex-1 bg-inverse fg-inverse rounded-lg px-4 py-2 cursor-pointer hover:bg-inverse-hover" %>
+          <%= form.submit "Export data", class: "flex-1 bg-inverse text-inverse rounded-lg px-4 py-2 cursor-pointer hover:bg-inverse-hover" %>
         </div>
       <% end %>
     </div>
diff --git a/app/views/holdings/_missing_price_tooltip.html.erb b/app/views/holdings/_missing_price_tooltip.html.erb
index f2f592011..94793a882 100644
--- a/app/views/holdings/_missing_price_tooltip.html.erb
+++ b/app/views/holdings/_missing_price_tooltip.html.erb
@@ -3,8 +3,8 @@
     <%= icon "info", size: "sm", color: "current" %>
     <%= tag.span t(".missing_data"), class: "font-normal text-xs" %>
   </div>
-  <div role="tooltip" data-tooltip-target="tooltip" class="tooltip bg-gray-700 text-sm p-2 rounded w-64">
-    <div class="fg-inverse">
+  <div role="tooltip" data-tooltip-target="tooltip" class="tooltip bg-inverse text-sm p-2 rounded w-64">
+    <div class="text-inverse">
       <%= t(".description") %>
     </div>
   </div>
diff --git a/app/views/investments/_value_tooltip.html.erb b/app/views/investments/_value_tooltip.html.erb
index 0cdeee278..55619f9ab 100644
--- a/app/views/investments/_value_tooltip.html.erb
+++ b/app/views/investments/_value_tooltip.html.erb
@@ -2,34 +2,34 @@
 
 <div data-controller="tooltip" data-tooltip-placement-value="right" data-tooltip-offset-value=10 data-tooltip-cross-axis-value=50>
   <%= icon("info", size: "sm") %>
-  <div role="tooltip" data-tooltip-target="tooltip" class="tooltip bg-gray-700 text-sm p-2 rounded w-64">
-    <div class="fg-inverse">
+  <div role="tooltip" data-tooltip-target="tooltip" class="tooltip bg-inverse text-sm p-2 rounded w-64">
+    <div class="text-inverse">
       <%= t(".total_value_tooltip") %>
     </div>
     <div class="flex pt-3">
-      <div class="text-gray-300">
+      <div class="text-inverse opacity-70">
         <%= t(".cash") %>
       </div>
-      <div class="fg-inverse ml-auto">
+      <div class="text-inverse ml-auto">
         <%= tag.p format_money(cash, precision: 0) %>
       </div>
     </div>
     <div class="flex">
-      <div class="text-gray-300">
+      <div class="text-inverse opacity-70">
         <%= t(".holdings") %>
       </div>
-      <div class="fg-inverse ml-auto">
+      <div class="text-inverse ml-auto">
         <%= tag.p format_money(holdings, precision: 0) %>
       </div>
     </div>
 
-    <hr class="my-2 border-secondary">
+    <hr class="my-2 border-inverse">
 
     <div class="flex">
-      <div class="text-gray-300">
+      <div class="text-inverse opacity-70">
         <%= t(".total") %>
       </div>
-      <div class="fg-inverse font-bold ml-auto">
+      <div class="text-inverse font-bold ml-auto">
         <%= tag.p format_money(balance, precision: 0) %>
       </div>
     </div>
diff --git a/app/views/invitations/new.html.erb b/app/views/invitations/new.html.erb
index f74b6a9d5..05f323981 100644
--- a/app/views/invitations/new.html.erb
+++ b/app/views/invitations/new.html.erb
@@ -18,7 +18,7 @@
         { label: t(".role_label") } %>
 
       <div class="w-full">
-        <%= form.submit t(".submit"), class: "bg-inverse fg-inverse rounded-lg px-4 py-2 w-full" %>
+        <%= form.submit t(".submit"), class: "bg-inverse text-inverse rounded-lg px-4 py-2 w-full" %>
       </div>
     <% end %>
   <% end %>
diff --git a/app/views/layouts/lookbooks.html.erb b/app/views/layouts/lookbooks.html.erb
index de1b9dc9b..30d6e8e52 100644
--- a/app/views/layouts/lookbooks.html.erb
+++ b/app/views/layouts/lookbooks.html.erb
@@ -8,7 +8,7 @@
     <%= javascript_include_tag "application", "data-turbo-track": "reload", defer: true %>
     <%= javascript_importmap_tags %>
   </head>
-  <body class="p-4 h-full bg-container <%= params.dig(:lookbook, :display, :container_classes) %>">
+  <body class="p-4 h-full bg-container text-primary <%= params.dig(:lookbook, :display, :container_classes) %>">
     <%= yield %>
   </body>
 </html>
diff --git a/app/views/pages/changelog.html.erb b/app/views/pages/changelog.html.erb
index d401f0d87..a31cba62e 100644
--- a/app/views/pages/changelog.html.erb
+++ b/app/views/pages/changelog.html.erb
@@ -5,7 +5,7 @@
     <div class="w-full md:w-1/3">
       <div class="md:px-3 flex items-center gap-3">
         <% if @release_notes[:avatar].present? %>
-          <div class="fg-inverse shrink-0 w-9 h-9">
+          <div class="text-inverse shrink-0 w-9 h-9">
             <%= image_tag @release_notes[:avatar], class: "rounded-full w-full h-full object-cover" %>
           </div>
         <% else %>
diff --git a/app/views/settings/hostings/_assistant_settings.html.erb b/app/views/settings/hostings/_assistant_settings.html.erb
index 082fddde7..37e5bbc65 100644
--- a/app/views/settings/hostings/_assistant_settings.html.erb
+++ b/app/views/settings/hostings/_assistant_settings.html.erb
@@ -54,12 +54,12 @@
         <%= button_to t(".disconnect_button"),
               disconnect_external_assistant_settings_hosting_path,
               method: :delete,
-              class: "bg-red-600 fg-inverse text-sm font-medium rounded-lg px-4 py-2 whitespace-nowrap",
+              class: "bg-red-600 text-inverse text-sm font-medium rounded-lg px-4 py-2 whitespace-nowrap",
               data: { turbo_confirm: {
                 title: t(".confirm_disconnect.title"),
                 body: t(".confirm_disconnect.body"),
                 accept: t(".disconnect_button"),
-                acceptClass: "w-full bg-red-600 fg-inverse rounded-xl text-center p-[10px] border mb-2"
+                acceptClass: "w-full bg-red-600 text-inverse rounded-xl text-center p-[10px] border mb-2"
               }} %>
       </div>
     <% end %>
diff --git a/app/views/settings/hostings/_danger_zone_settings.html.erb b/app/views/settings/hostings/_danger_zone_settings.html.erb
index 18cfd4d03..23e26644e 100644
--- a/app/views/settings/hostings/_danger_zone_settings.html.erb
+++ b/app/views/settings/hostings/_danger_zone_settings.html.erb
@@ -7,12 +7,12 @@
       </div>
       <%=
             button_to t("settings.hostings.show.clear_cache"), clear_cache_settings_hosting_path, method: :delete,
-              class: "w-full md:w-auto bg-yellow-600 fg-inverse text-sm font-medium rounded-lg px-4 py-2",
+              class: "w-full md:w-auto bg-yellow-600 text-inverse text-sm font-medium rounded-lg px-4 py-2",
               data: { turbo_confirm: {
                 title: t("settings.hostings.show.confirm_clear_cache.title"),
                 body: t("settings.hostings.show.confirm_clear_cache.body"),
                 accept: t("settings.hostings.show.clear_cache"),
-                acceptClass: "w-full bg-yellow-600 fg-inverse rounded-xl text-center p-[10px] border mb-2"
+                acceptClass: "w-full bg-yellow-600 text-inverse rounded-xl text-center p-[10px] border mb-2"
               }}
       %>
     </div>
diff --git a/app/views/settings/profiles/show.html.erb b/app/views/settings/profiles/show.html.erb
index c2f2dc158..1e50dd379 100644
--- a/app/views/settings/profiles/show.html.erb
+++ b/app/views/settings/profiles/show.html.erb
@@ -70,7 +70,7 @@
             <div class="flex gap-2 items-center justify-between bg-container p-4 border border-alpha-black-25 rounded-lg">
               <div class="flex gap-2 items-center">
                 <div class="w-9 h-9 shrink-0">
-                  <div class="fg-inverse w-full h-full bg-surface-inset rounded-full flex items-center justify-center text-lg uppercase"><%= invitation.email[0] %></div>
+                  <div class="text-inverse w-full h-full bg-surface-inset rounded-full flex items-center justify-center text-lg uppercase"><%= invitation.email[0] %></div>
                 </div>
                 <div class="flex">
                   <p class="text-primary font-medium text-sm"><%= invitation.email %></p>
diff --git a/app/views/shared/_money_field.html.erb b/app/views/shared/_money_field.html.erb
index c4f34f542..21c773da8 100644
--- a/app/views/shared/_money_field.html.erb
+++ b/app/views/shared/_money_field.html.erb
@@ -22,7 +22,7 @@
       <div class="form-field__actions">
         <div data-controller="tooltip">
           <%= icon "help-circle", size: "sm", color: "default", class: "cursor-help" %>
-          <div role="tooltip" data-tooltip-target="tooltip" class="tooltip bg-gray-700 text-sm p-2 rounded w-64 text-white">
+          <div role="tooltip" data-tooltip-target="tooltip" class="tooltip bg-inverse text-inverse text-sm p-2 rounded w-64">
             <%= options[:label_tooltip] %>
           </div>
         </div>
diff --git a/app/views/shared/_text_tooltip.erb b/app/views/shared/_text_tooltip.erb
index a576b114c..b95fb4712 100644
--- a/app/views/shared/_text_tooltip.erb
+++ b/app/views/shared/_text_tooltip.erb
@@ -1,5 +1,5 @@
-<div role="tooltip" data-tooltip-target="tooltip" class="tooltip bg-gray-700 text-sm px-1.5 py-1 rounded-md">
-  <div class="fg-inverse font-normal max-w-[200px]">
+<div role="tooltip" data-tooltip-target="tooltip" class="tooltip bg-inverse text-sm px-1.5 py-1 rounded-md">
+  <div class="text-inverse font-normal max-w-[200px]">
     <%= tooltip_text %>
   </div>
 </div>
diff --git a/app/views/shared/notifications/_cta.html.erb b/app/views/shared/notifications/_cta.html.erb
index c428b66d1..9232ac591 100644
--- a/app/views/shared/notifications/_cta.html.erb
+++ b/app/views/shared/notifications/_cta.html.erb
@@ -3,7 +3,7 @@
 <div id="cta">
   <%= tag.div class: "relative flex gap-3 rounded-lg bg-container p-4 group w-full md:max-w-80 shadow-border-xs", data: { controller: "element-removal" } do %>
     <div class="h-5 w-5 shrink-0 p-px text-primary">
-      <div class="flex h-full items-center justify-center rounded-full bg-success fg-inverse">
+      <div class="flex h-full items-center justify-center rounded-full bg-success text-inverse">
         <%= icon "check", size: "xs", color: "current" %>
       </div>
     </div>
diff --git a/design/tokens/README.md b/design/tokens/README.md
index eb40a6d00..17a0ab11b 100644
--- a/design/tokens/README.md
+++ b/design/tokens/README.md
@@ -100,7 +100,7 @@ The same syntax appears inside composite values like `shadow.xs.$value`: `"0px 1
 - `utility.border-divider`: the value is a plain class string (`border-tertiary`) instead of a `{ref}`. The build treats values without `{}` as raw `@apply` arguments.
 - `utility.bg-overlay`: uses `sure.utility.raw: "background-color"` because it needs alpha rendering instead of `@apply`.
 - `utility.bg-loader`: uses `sure.compose` to apply two utilities together (`bg-surface-inset animate-pulse`).
-- `utility.button-bg-ghost-hover`: its dark value is a multi-class string (`bg-gray-800 fg-inverse`), not a single ref. The build accepts both forms.
+- `utility.button-bg-ghost-hover`: its dark value is a multi-class string (`bg-gray-800 text-inverse`), not a single ref. The build accepts both forms.
 
 ## Consumers
 
diff --git a/design/tokens/sure.tokens.json b/design/tokens/sure.tokens.json
index 48cbd46b6..e8c3ce27c 100644
--- a/design/tokens/sure.tokens.json
+++ b/design/tokens/sure.tokens.json
@@ -1,6 +1,6 @@
 {
   "$schema": "https://design-tokens.github.io/community-group/format/",
-  "$version": "1.0.0",
+  "$version": "2.0.0",
   "$description": "Sure design tokens. Single source of truth. Hand-edit; run `npm run tokens:build` to regenerate CSS. Template syntax in $value strings: `{path.to.token}` resolves to `var(--path-to-token)`; `{path|N%}` becomes `--alpha(var(--path) / N%)`. Utility tokens whose value lacks `{}` are treated as raw Tailwind class lists for @apply.",
 
   "font": {
@@ -275,15 +275,6 @@
       "$extensions": { "sure.compose": ["bg-surface-inset", "animate-pulse"] }
     },
 
-    "fg-gray":              { "$type": "utility", "$value": "{color.gray.500}", "$extensions": { "sure.utility": { "prefix": "text" }, "sure.dark": "{color.gray.400}" } },
-    "fg-contrast":          { "$type": "utility", "$value": "{color.gray.400}", "$extensions": { "sure.utility": { "prefix": "text" }, "sure.dark": "{color.gray.500}" } },
-    "fg-inverse":           { "$type": "utility", "$value": "{color.white}",    "$extensions": { "sure.utility": { "prefix": "text" }, "sure.dark": "{color.gray.900}" } },
-    "fg-primary":           { "$type": "utility", "$value": "{color.gray.900}", "$extensions": { "sure.utility": { "prefix": "text" }, "sure.dark": "{color.white}" } },
-    "fg-primary-variant":   { "$type": "utility", "$value": "{color.gray.800}", "$extensions": { "sure.utility": { "prefix": "text" }, "sure.dark": "{color.gray.50}" } },
-    "fg-secondary":         { "$type": "utility", "$value": "{color.gray.50}",  "$extensions": { "sure.utility": { "prefix": "text" }, "sure.dark": "{color.gray.400}" } },
-    "fg-secondary-variant": { "$type": "utility", "$value": "{color.gray.100}", "$extensions": { "sure.utility": { "prefix": "text" }, "sure.dark": "{color.gray.500}" } },
-    "fg-subdued":           { "$type": "utility", "$value": "{color.gray.400}", "$extensions": { "sure.utility": { "prefix": "text" }, "sure.dark": "{color.gray.500}" } },
-
     "text-primary":   { "$type": "utility", "$value": "{color.gray.900}", "$extensions": { "sure.utility": { "prefix": "text" }, "sure.dark": "{color.white}" } },
     "text-inverse":   { "$type": "utility", "$value": "{color.white}",    "$extensions": { "sure.utility": { "prefix": "text" }, "sure.dark": "{color.gray.900}" } },
     "text-secondary": { "$type": "utility", "$value": "{color.gray.500}", "$extensions": { "sure.utility": { "prefix": "text" }, "sure.dark": "{color.gray.300}" } },
@@ -338,6 +329,7 @@
     "border-subdued":     { "$type": "utility", "$value": "{color.alpha-black.50}",  "$extensions": { "sure.utility": { "prefix": "border" }, "sure.dark": "{color.alpha-white.100}" } },
     "border-solid":       { "$type": "utility", "$value": "{color.black}",           "$extensions": { "sure.utility": { "prefix": "border" }, "sure.dark": "{color.white}" } },
     "border-destructive": { "$type": "utility", "$value": "{color.red.500}",         "$extensions": { "sure.utility": { "prefix": "border" }, "sure.dark": "{color.red.400}" } },
+    "border-inverse":     { "$type": "utility", "$value": "{color.alpha-white.200}", "$extensions": { "sure.utility": { "prefix": "border" }, "sure.dark": "{color.alpha-black.300}" } },
 
     "button-bg-primary":           { "$type": "utility", "$value": "{color.gray.900}", "$extensions": { "sure.utility": { "prefix": "bg" }, "sure.dark": "{color.white}" } },
     "button-bg-primary-hover":     { "$type": "utility", "$value": "{color.gray.800}", "$extensions": { "sure.utility": { "prefix": "bg" }, "sure.dark": "{color.gray.50}" } },
@@ -346,7 +338,7 @@
     "button-bg-disabled":          { "$type": "utility", "$value": "{color.gray.50}",  "$extensions": { "sure.utility": { "prefix": "bg" }, "sure.dark": "{color.gray.700}" } },
     "button-bg-destructive":       { "$type": "utility", "$value": "{color.red.500}",  "$extensions": { "sure.utility": { "prefix": "bg" }, "sure.dark": "{color.red.400}" } },
     "button-bg-destructive-hover": { "$type": "utility", "$value": "{color.red.600}",  "$extensions": { "sure.utility": { "prefix": "bg" }, "sure.dark": "{color.red.500}" } },
-    "button-bg-ghost-hover":       { "$type": "utility", "$value": "{color.gray.50}",  "$extensions": { "sure.utility": { "prefix": "bg" }, "sure.dark": "bg-gray-800 fg-inverse" } },
+    "button-bg-ghost-hover":       { "$type": "utility", "$value": "{color.gray.50}",  "$extensions": { "sure.utility": { "prefix": "bg" }, "sure.dark": "bg-gray-800 text-inverse" } },
     "button-bg-outline-hover":     { "$type": "utility", "$value": "{color.gray.100}", "$extensions": { "sure.utility": { "prefix": "bg" }, "sure.dark": "{color.gray.700}" } },
 
     "tab-item-active":  { "$type": "utility", "$value": "{color.white}",     "$extensions": { "sure.utility": { "prefix": "bg" }, "sure.dark": "{color.gray.700}" } },
diff --git a/test/components/previews/design_tokens_preview.rb b/test/components/previews/design_tokens_preview.rb
index 13bf588a3..688cc6ffd 100644
--- a/test/components/previews/design_tokens_preview.rb
+++ b/test/components/previews/design_tokens_preview.rb
@@ -48,10 +48,7 @@ class DesignTokensPreview < ViewComponent::Preview
   end
 
   def text
-    render_with_template(locals: {
-      text_utilities: collect_utilities { |name| name.start_with?("text-") },
-      fg_utilities:   collect_utilities { |name| name.start_with?("fg-") }
-    })
+    render_with_template(locals: { utilities: collect_utilities { |name| name.start_with?("text-") } })
   end
 
   def borders
diff --git a/test/components/previews/design_tokens_preview/effects.html.erb b/test/components/previews/design_tokens_preview/effects.html.erb
index 483d0ce7f..3ea59955e 100644
--- a/test/components/previews/design_tokens_preview/effects.html.erb
+++ b/test/components/previews/design_tokens_preview/effects.html.erb
@@ -14,7 +14,7 @@
     <div class="grid gap-3 grid-cols-2 sm:grid-cols-3 lg:grid-cols-5">
       <% shadows.each do |s| %>
         <div class="<%= card %>">
-          <div class="h-16 w-full rounded-md bg-container" style="box-shadow: <%= s[:light_resolved] %>"></div>
+          <div class="h-16 w-full rounded-md bg-container" style="box-shadow: var(<%= s[:var] %>)"></div>
           <p class="<%= label %>"><%= s[:var] %></p>
           <p class="<%= meta %> truncate"><%= s[:light_raw] %></p>
           <% if s[:dark_raw] %>
diff --git a/test/components/previews/design_tokens_preview/text.html.erb b/test/components/previews/design_tokens_preview/text.html.erb
index e46d27a2e..8425e280e 100644
--- a/test/components/previews/design_tokens_preview/text.html.erb
+++ b/test/components/previews/design_tokens_preview/text.html.erb
@@ -3,59 +3,34 @@
   meta        = "text-xs text-secondary font-mono"
   light_ctx   = "rounded p-3 bg-surface"
   dark_ctx    = "rounded p-3 bg-gray-900"
-
-  render_group = ->(items) {
-    capture do
-      content_tag(:div, class: "grid gap-3 grid-cols-1 lg:grid-cols-2") do
-        safe_join(items.map do |u|
-          content_tag(:div, class: card) do
-            safe_join([
-              content_tag(:div, class: "grid grid-cols-2 gap-2") do
-                safe_join([
-                  content_tag(:div, class: light_ctx) do
-                    content_tag(:p, "Quick brown fox", class: "text-sm font-medium #{u[:name]}")
-                  end,
-                  content_tag(:div, class: dark_ctx) do
-                    content_tag(:p, "Quick brown fox", class: "text-sm font-medium #{u[:name]}")
-                  end
-                ])
-              end,
-              content_tag(:div, class: "space-y-0.5") do
-                safe_join([
-                  content_tag(:p, u[:name], class: "text-xs font-medium text-primary"),
-                  content_tag(:p, u[:light_resolved] || u[:light_value], class: "#{meta} truncate"),
-                  (u[:dark_value] ? content_tag(:p, "dark: #{u[:dark_resolved] || u[:dark_value]}", class: "#{meta} truncate text-subdued") : nil)
-                ].compact)
-              end
-            ])
-          end
-        end)
-      end
-    end
-  }
 %>
-<div class="bg-surface min-h-screen p-6 space-y-10">
+<div class="bg-surface min-h-screen p-6 space-y-6">
   <header>
     <h2 class="text-2xl font-semibold text-primary">Text &amp; foregrounds</h2>
     <p class="text-sm text-secondary">
-      Each example renders the literal class on a light <em>and</em> a dark surface so utilities meant for inverse contexts show their intended state.
+      <code class="font-mono">text-*</code> utilities. Each example renders the literal class on a light <em>and</em> a dark surface so utilities meant for inverse contexts show their intended state.
     </p>
   </header>
 
-  <section class="space-y-3">
-    <header class="space-y-1">
-      <h3 class="text-lg font-medium text-primary"><code class="font-mono">text-*</code> <span class="text-xs text-secondary font-normal">(canonical, ~2,000 uses across the codebase)</span></h3>
-    </header>
-    <%= render_group.call(text_utilities) %>
-  </section>
-
-  <section class="space-y-3">
-    <header class="space-y-1">
-      <h3 class="text-lg font-medium text-primary"><code class="font-mono">fg-*</code> <span class="text-xs text-warning font-normal">(legacy — prefer <code class="font-mono">text-*</code>)</span></h3>
-      <p class="text-sm text-secondary">
-        Older namespace, ~40 uses left in the codebase. Most are 1:1 duplicates of a <code class="font-mono">text-*</code> equivalent. Tracked for migration; no new code should reference these.
-      </p>
-    </header>
-    <%= render_group.call(fg_utilities) %>
-  </section>
+  <div class="grid gap-3 grid-cols-1 lg:grid-cols-2">
+    <% utilities.each do |u| %>
+      <div class="<%= card %>">
+        <div class="grid grid-cols-2 gap-2">
+          <div class="<%= light_ctx %>">
+            <p class="text-sm font-medium <%= u[:name] %>">Quick brown fox</p>
+          </div>
+          <div class="<%= dark_ctx %>">
+            <p class="text-sm font-medium <%= u[:name] %>">Quick brown fox</p>
+          </div>
+        </div>
+        <div class="space-y-0.5">
+          <p class="text-xs font-medium text-primary"><%= u[:name] %></p>
+          <p class="<%= meta %> truncate"><%= u[:light_resolved] || u[:light_value] %></p>
+          <% if u[:dark_value] %>
+            <p class="<%= meta %> truncate text-subdued">dark: <%= u[:dark_resolved] || u[:dark_value] %></p>
+          <% end %>
+        </div>
+      </div>
+    <% end %>
+  </div>
 </div>
diff --git a/test/components/previews/menu_component_preview.rb b/test/components/previews/menu_component_preview.rb
index 592b276c1..78049537b 100644
--- a/test/components/previews/menu_component_preview.rb
+++ b/test/components/previews/menu_component_preview.rb
@@ -22,7 +22,7 @@ class MenuComponentPreview < ViewComponent::Preview
     def menu_contents(menu)
       menu.with_header do
         content_tag(:div, class: "p-3") do
-          content_tag(:h3, "Menu header", class: "font-medium text-gray-900")
+          content_tag(:h3, "Menu header", class: "font-medium text-primary")
         end
       end
 
@@ -35,8 +35,8 @@ class MenuComponentPreview < ViewComponent::Preview
       menu.with_custom_content do
         content_tag(:div, class: "p-4") do
           safe_join([
-            content_tag(:h3, "Custom content header", class: "font-medium text-gray-900"),
-            content_tag(:p, "Some custom content", class: "text-sm text-gray-500")
+            content_tag(:h3, "Custom content header", class: "font-medium text-primary"),
+            content_tag(:p, "Some custom content", class: "text-sm text-secondary")
           ])
         end
       end