From 2d333f73843a4b00d57dd24f351fa42a41bd0e49 Mon Sep 17 00:00:00 2001
From: Burcu Noyan <burcunoyan@gmail.com>
Date: Thu, 2 Jul 2026 17:40:31 -0400
Subject: [PATCH] Ship a semantic token layer with dark mode in boxel-ui

Own the semantic design tokens in the addon instead of leaving them to consumers:

- theme.css (new): defines the full semantic contract (--primary, --foreground,  --muted, --card, --border, --destructive, --sidebar-*, shadows, etc.) mapped onto the --boxel-* palette as a default light theme, plus a dark theme via .dark / [data-theme="dark"] and an opt-in [data-theme="system"] scope. Also emits an inherited --boxel-color-scheme signal for cards to key off.
- variables.css: mark the raw --boxel-* palette as an internal implementation detail; component/card styles should consume the semantic tokens.
- button, multi-select: migrate bare palette border refs onto var(--border, ...).
---
 .../addon/src/components/button/index.gts     |   2 +-
 .../src/components/multi-select/index.gts     |   4 +-
 .../addon/src/components/tooltip/index.gts    |  86 ++---
 .../addon/src/components/tooltip/usage.gts    |  20 +-
 packages/boxel-ui/addon/src/styles/theme.css  | 139 ++++++++
 .../boxel-ui/addon/src/styles/variables.css   |  22 +-
 packages/boxel-ui/test-app/app/app.js         |   1 +
 .../boxel-ui/test-app/app/templates/index.gts | 309 +++++++++++++++---
 packages/host/app/app.ts                      |   1 +
 9 files changed, 471 insertions(+), 113 deletions(-)
 create mode 100644 packages/boxel-ui/addon/src/styles/theme.css

diff --git a/packages/boxel-ui/addon/src/components/button/index.gts b/packages/boxel-ui/addon/src/components/button/index.gts
index aa84415a956..03b3060f6ce 100644
--- a/packages/boxel-ui/addon/src/components/button/index.gts
+++ b/packages/boxel-ui/addon/src/components/button/index.gts
@@ -188,7 +188,7 @@ const ButtonComponent: TemplateOnlyComponent<Signature> = <template>
       a.boxel-button:not([href]),
       a.boxel-button[href=''],
       a.boxel-button.disabled-link {
-        --boxel-button-color: var(--boxel-border-color);
+        --boxel-button-color: var(--border, var(--boxel-border-color));
         --boxel-button-border: 1px solid var(--boxel-button-color);
         --boxel-button-text-color: var(--boxel-450);
         --boxel-button-box-shadow: none;
diff --git a/packages/boxel-ui/addon/src/components/multi-select/index.gts b/packages/boxel-ui/addon/src/components/multi-select/index.gts
index 799e5dc0b70..0a699222b79 100644
--- a/packages/boxel-ui/addon/src/components/multi-select/index.gts
+++ b/packages/boxel-ui/addon/src/components/multi-select/index.gts
@@ -151,7 +151,7 @@ export class BoxelMultiSelectBasic<ItemT> extends Component<Signature<ItemT>> {
         padding: var(--boxel-sp-xxs) var(--boxel-sp-sm);
       }
       .boxel-multi-select__dropdown--rounded.ember-power-select-dropdown {
-        border: 1px solid var(--boxel-border-color);
+        border: 1px solid var(--border, var(--boxel-border-color));
         border-radius: var(--boxel-border-radius-sm);
       }
     </style>
@@ -161,7 +161,7 @@ export class BoxelMultiSelectBasic<ItemT> extends Component<Signature<ItemT>> {
         display: flex;
         align-items: stretch;
         overflow: hidden;
-        border: 1px solid var(--boxel-border-color);
+        border: 1px solid var(--border, var(--boxel-border-color));
         border-radius: var(--boxel-border-radius-sm);
         max-width: 100%;
         width: 100%;
diff --git a/packages/boxel-ui/addon/src/components/tooltip/index.gts b/packages/boxel-ui/addon/src/components/tooltip/index.gts
index 1b82dda11d9..adcf9421ac2 100644
--- a/packages/boxel-ui/addon/src/components/tooltip/index.gts
+++ b/packages/boxel-ui/addon/src/components/tooltip/index.gts
@@ -11,11 +11,22 @@ import { Velcro } from 'ember-velcro';
 
 import cn from '../../helpers/cn.ts';
 
+export const TOOLTIP_VARIANTS = [
+  'default',
+  'main',
+  'primary',
+  'secondary',
+  'accent',
+  'muted',
+  'destructive',
+] as const;
+export type ThemeVariant = (typeof TOOLTIP_VARIANTS)[number];
+
 interface Signature {
   Args: {
     offset?: number;
     placement?: MiddlewareState['placement'];
-    variant?: 'primary' | 'secondary' | 'muted' | 'destructive' | 'default';
+    variant?: ThemeVariant;
   };
   Blocks: {
     content: [];
@@ -71,11 +82,15 @@ export default class Tooltip extends Component<Signature> {
     const themeVars = [
       '--background',
       '--foreground',
+      '--popover',
+      '--popover-foreground',
       '--border',
       '--primary',
       '--primary-foreground',
       '--secondary',
       '--secondary-foreground',
+      '--accent',
+      '--accent-foreground',
       '--muted',
       '--muted-foreground',
       '--destructive',
@@ -185,19 +200,10 @@ export default class Tooltip extends Component<Signature> {
       }
 
       .tooltip {
-        --tooltip-background-color: var(
-          --boxel-tooltip-background-color,
-          var(--background, rgb(0 0 0 / 80%))
-        );
-        --tooltip-text-color: var(
-          --boxel-tooltip-text-color,
-          var(--foreground, var(--boxel-light))
-        );
         --tooltip-border-color: var(
           --boxel-tooltip-border-color,
-          var(--border, var(--boxel-light-500))
+          var(--boxel-light-35)
         );
-
         background-color: var(--tooltip-background-color);
         box-shadow: 0 0 0 1px var(--tooltip-border-color);
         color: var(--tooltip-text-color);
@@ -220,75 +226,77 @@ export default class Tooltip extends Component<Signature> {
       .variant-default {
         --tooltip-background-color: var(
           --boxel-tooltip-background-color,
-          var(--background, rgb(0 0 0 / 80%))
+          var(--boxel-dark-80)
         );
         --tooltip-text-color: var(
           --boxel-tooltip-text-color,
-          var(--foreground, var(--boxel-light))
+          var(--boxel-light)
         );
-        --tooltip-border-color: var(
-          --boxel-tooltip-border-color,
-          var(--border, var(--boxel-light-500))
+      }
+
+      .variant-main {
+        --tooltip-background-color: var(
+          --boxel-tooltip-background-color,
+          var(--popover, var(--background))
+        );
+        --tooltip-text-color: var(
+          --boxel-tooltip-text-color,
+          var(--popover-foreground, var(--foreground))
         );
       }
 
       .variant-primary {
         --tooltip-background-color: var(
           --boxel-tooltip-background-color,
-          var(--primary, var(--boxel-600))
+          var(--primary)
         );
         --tooltip-text-color: var(
           --boxel-tooltip-text-color,
-          var(--primary-foreground, var(--boxel-light))
-        );
-        --tooltip-border-color: var(
-          --boxel-tooltip-border-color,
-          var(--primary, var(--boxel-600))
+          var(--primary-foreground)
         );
       }
 
       .variant-secondary {
         --tooltip-background-color: var(
           --boxel-tooltip-background-color,
-          var(--secondary, var(--boxel-400))
+          var(--secondary)
         );
         --tooltip-text-color: var(
           --boxel-tooltip-text-color,
-          var(--secondary-foreground, var(--boxel-dark))
+          var(--secondary-foreground)
         );
-        --tooltip-border-color: var(
-          --boxel-tooltip-border-color,
-          var(--secondary, var(--boxel-400))
+      }
+
+      .variant-accent {
+        --tooltip-background-color: var(
+          --boxel-tooltip-background-color,
+          var(--accent)
+        );
+        --tooltip-text-color: var(
+          --boxel-tooltip-text-color,
+          var(--accent-foreground)
         );
       }
 
       .variant-muted {
         --tooltip-background-color: var(
           --boxel-tooltip-background-color,
-          var(--muted, var(--boxel-200))
+          var(--muted)
         );
         --tooltip-text-color: var(
           --boxel-tooltip-text-color,
-          var(--muted-foreground, var(--boxel-dark))
-        );
-        --tooltip-border-color: var(
-          --boxel-tooltip-border-color,
-          var(--muted, var(--boxel-200))
+          var(--muted-foreground)
         );
       }
 
       .variant-destructive {
         --tooltip-background-color: var(
           --boxel-tooltip-background-color,
-          var(--destructive, var(--boxel-600))
+          var(--destructive)
         );
         --tooltip-text-color: var(
           --boxel-tooltip-text-color,
-          var(--destructive-foreground, var(--boxel-light))
-        );
-        --tooltip-border-color: var(
-          --boxel-tooltip-border-color,
-          var(--destructive, var(--boxel-600))
+          var(--destructive-foreground)
         );
       }
 
diff --git a/packages/boxel-ui/addon/src/components/tooltip/usage.gts b/packages/boxel-ui/addon/src/components/tooltip/usage.gts
index cc762449011..2e8b4f98713 100644
--- a/packages/boxel-ui/addon/src/components/tooltip/usage.gts
+++ b/packages/boxel-ui/addon/src/components/tooltip/usage.gts
@@ -12,27 +12,15 @@ import {
 
 import { cssVar } from '../../helpers.ts';
 import BoxelButton from '../button/index.gts';
-import BoxelTooltip from './index.gts';
+import BoxelTooltip, { type ThemeVariant, TOOLTIP_VARIANTS } from './index.gts';
 
 export default class TooltipUsage extends Component {
-  tooltipVariants = ['default', 'primary', 'secondary', 'muted', 'destructive'];
-  tooltipVariantDefault:
-    | undefined
-    | 'primary'
-    | 'secondary'
-    | 'muted'
-    | 'destructive'
-    | 'default' = undefined;
+  tooltipVariants = TOOLTIP_VARIANTS;
+  tooltipVariantDefault?: ThemeVariant;
 
   @tracked placement: MiddlewareState['placement'] = 'bottom';
   @tracked offset = 6;
-  @tracked variant:
-    | undefined
-    | 'primary'
-    | 'secondary'
-    | 'muted'
-    | 'destructive'
-    | 'default' = undefined;
+  @tracked variant?: ThemeVariant;
 
   @cssVariable({ cssClassName: 'header-freestyle-container' })
   declare tooltipBackgroundColor: CSSVariableInfo;
diff --git a/packages/boxel-ui/addon/src/styles/theme.css b/packages/boxel-ui/addon/src/styles/theme.css
new file mode 100644
index 00000000000..362f9e68fc2
--- /dev/null
+++ b/packages/boxel-ui/addon/src/styles/theme.css
@@ -0,0 +1,139 @@
+/* Boxel UI — semantic token contract + default (light) theme.
+
+   This file is the source of record for the semantic design tokens that
+   boxel-ui components consume (--primary, --foreground, --muted, etc.).
+   Shipping it from the addon means components render correctly with zero
+   host configuration — a consumer that imports the addon's styles gets a
+   complete, working theme by default.
+
+   The default values below map the semantic tokens onto the --boxel-*
+   palette declared in variables.css, so the palette remains the single
+   underlying source of truth for brand colors. A consumer overrides any
+   token by redeclaring it on :root (or a scoped element) after this file.
+
+   The full list of tokens declared here is the contract every theme must
+   satisfy. The dark-mode counterpart (a `.dark` / `[data-theme='dark']` scope)
+   is layered on separately, below.
+*/
+
+/* Light — the default theme, and the explicit `data-theme="light"` scope used
+   to force light back on inside a dark subtree. Both resolve to the same
+   values. */
+:root,
+[data-theme='light'] {
+  /* surfaces */
+  --background: var(--boxel-light);
+  --foreground: var(--boxel-dark);
+  --card: var(--boxel-light);
+  --card-foreground: var(--boxel-dark);
+  --popover: var(--boxel-light);
+  --popover-foreground: var(--boxel-dark);
+
+  /* roles */
+  --primary: var(--boxel-highlight);
+  --primary-foreground: var(--boxel-dark);
+  --secondary: var(--boxel-200);
+  --secondary-foreground: var(--boxel-dark);
+  --muted: var(--boxel-100);
+  --muted-foreground: var(--boxel-500);
+  --accent: var(--boxel-200);
+  --accent-foreground: var(--boxel-dark);
+  --destructive: var(--boxel-danger);
+  --destructive-foreground: var(--boxel-50);
+
+  /* form + focus */
+  --border: var(--boxel-border-color);
+  --input: var(--boxel-light);
+  --ring: var(--boxel-highlight);
+
+  /* charts */
+  --chart-1: var(--boxel-fuschia);
+  --chart-2: var(--boxel-purple);
+  --chart-3: var(--boxel-lime);
+  --chart-4: var(--boxel-blue);
+  --chart-5: var(--boxel-green);
+
+  /* sidebar */
+  --sidebar: var(--boxel-light);
+  --sidebar-foreground: var(--boxel-dark);
+  --sidebar-primary: var(--boxel-dark);
+  --sidebar-primary-foreground: var(--boxel-light);
+  --sidebar-accent: var(--boxel-200);
+  --sidebar-accent-foreground: var(--boxel-dark);
+  --sidebar-border: var(--boxel-border-color);
+  --sidebar-ring: var(--boxel-highlight);
+
+  /* typography */
+  --font-sans:
+    'IBM Plex Sans', 'Helvetica Neue', Arial, ui-sans-serif, sans-serif,
+    system-ui;
+  --font-serif: 'IBM Plex Serif', 'Georgia', Times, serif;
+  --font-mono:
+    'IBM Plex Mono', 'Menlo', 'Courier New', Courier, ui-monospace, monospace;
+  --tracking-normal: 0.01em;
+
+  /* geometry + spacing */
+  --radius: 0.625rem;
+  --spacing: 0.25rem;
+
+  /* shadow scale */
+  --shadow-x: 0;
+  --shadow-y: 1px;
+  --shadow-blur: 3px;
+  --shadow-spread: 0px;
+  --shadow-opacity: 0.1;
+  --shadow-color: var(--boxel-dark);
+  --shadow-2xs: 0 1px 3px 0px hsl(0 0% 0% / 0.05);
+  --shadow-xs: 0 1px 3px 0px hsl(0 0% 0% / 0.05);
+  --shadow-sm:
+    0 1px 3px 0px hsl(0 0% 0% / 0.1), 0 1px 2px -1px hsl(0 0% 0% / 0.1);
+  --shadow: 0 1px 3px 0px hsl(0 0% 0% / 0.1), 0 1px 2px -1px hsl(0 0% 0% / 0.1);
+  --shadow-md:
+    0 1px 3px 0px hsl(0 0% 0% / 0.1), 0 2px 4px -1px hsl(0 0% 0% / 0.1);
+  --shadow-lg:
+    0 1px 3px 0px hsl(0 0% 0% / 0.1), 0 4px 6px -1px hsl(0 0% 0% / 0.1);
+  --shadow-xl:
+    0 1px 3px 0px hsl(0 0% 0% / 0.1), 0 8px 10px -1px hsl(0 0% 0% / 0.1);
+  --shadow-2xl: 0 1px 3px 0px hsl(0 0% 0% / 0.25);
+}
+
+/* ── Dark mode ──────────────────────────────────────────────────────────────
+   Opt-in and explicit: add class `dark` or `data-theme="dark"` to <html>, or to
+   any subtree you want themed dark. Force light back on inside a dark subtree
+   with `data-theme="light"` (see the light block above).
+
+   OS-driven dark (`prefers-color-scheme` / a `data-theme="system"` mode) is
+   intentionally NOT wired up yet — it needs to resolve in both directions
+   (falling back to light when the OS is light, including inside a dark subtree),
+   so it is deferred until that feature is implemented.
+*/
+.dark,
+[data-theme='dark'] {
+  --background: var(--boxel-700);
+  --foreground: var(--boxel-light);
+  --card: var(--boxel-650);
+  --card-foreground: var(--boxel-light);
+  --popover: #4f4b57;
+  --popover-foreground: var(--boxel-light);
+  --primary: var(--boxel-highlight);
+  --primary-foreground: var(--boxel-dark);
+  --secondary: #46434e;
+  --secondary-foreground: var(--boxel-light);
+  --muted: #34313c;
+  --muted-foreground: #b6b6be;
+  --accent: #797788;
+  --accent-foreground: var(--boxel-light);
+  --destructive: var(--boxel-danger);
+  --destructive-foreground: var(--boxel-light-100);
+  --border: var(--boxel-550);
+  --input: var(--boxel-dark);
+  --ring: var(--boxel-highlight);
+  --sidebar: #555366;
+  --sidebar-foreground: var(--boxel-light);
+  --sidebar-primary: var(--boxel-highlight);
+  --sidebar-primary-foreground: var(--boxel-dark);
+  --sidebar-accent: #797788;
+  --sidebar-accent-foreground: var(--boxel-light);
+  --sidebar-border: var(--boxel-550);
+  --sidebar-ring: var(--boxel-highlight);
+}
diff --git a/packages/boxel-ui/addon/src/styles/variables.css b/packages/boxel-ui/addon/src/styles/variables.css
index c368c0dc62b..04461d7f129 100644
--- a/packages/boxel-ui/addon/src/styles/variables.css
+++ b/packages/boxel-ui/addon/src/styles/variables.css
@@ -152,7 +152,17 @@
   --boxel-xl-container: 65rem; /* 1040px */
   --boxel-xxl-container: 83.76rem; /* 1340px */
 
-  /* COLOR PALETTE */
+  /* COLOR PALETTE
+   *
+   * INTERNAL — these raw palette values are an implementation detail, not the
+   * public theming API. Component styles and cards should consume the semantic
+   * tokens defined in theme.css (--primary, --foreground, --background, --muted,
+   * --border, --destructive, etc.), which are mapped onto this palette in the
+   * default theme. Referencing a raw --boxel-<shade> for a semantic color role
+   * bypasses theming and breaks under custom themes / dark mode; reach for the
+   * semantic token instead. Keep a raw palette reference only when a specific
+   * fixed shade is genuinely intended, independent of the active theme.
+   */
 
   /**** Revisited Colors BOXEL-UI ****/
   --boxel-50: #f5f5f5;
@@ -190,9 +200,13 @@
   /* Primary colors */
   --boxel-light: #fff;
   --boxel-dark: #000;
-  --boxel-dark-hover: rgba(0, 0, 0, 0.1);
-  --boxel-darker-hover: rgba(0, 0, 0, 0.5);
-  --boxel-light-hover-35: rgba(255, 255, 255, 0.35);
+  --boxel-light-35: rgba(255, 255, 255, 0.35);
+  --boxel-dark-10: rgba(0, 0, 0, 0.1);
+  --boxel-dark-50: rgba(0, 0, 0, 0.5);
+  --boxel-dark-80: rgba(0, 0, 0, 0.8);
+  --boxel-dark-hover: var(--boxel-dark-10);
+  --boxel-darker-hover: var(--boxel-dark-50);
+  --boxel-light-hover-35: var(--boxel-light-35);
 
   --boxel-highlight: var(--boxel-teal);
   --boxel-highlight-hover: var(--boxel-dark-teal);
diff --git a/packages/boxel-ui/test-app/app/app.js b/packages/boxel-ui/test-app/app/app.js
index 6a0b4978500..d06bab62e47 100644
--- a/packages/boxel-ui/test-app/app/app.js
+++ b/packages/boxel-ui/test-app/app/app.js
@@ -5,6 +5,7 @@ import config from 'test-app/config/environment';
 import '@cardstack/boxel-ui/styles/global.css';
 import '@cardstack/boxel-ui/styles/fonts.css';
 import '@cardstack/boxel-ui/styles/variables.css';
+import '@cardstack/boxel-ui/styles/theme.css';
 import './deprecation-workflow';
 
 export default class App extends Application {
diff --git a/packages/boxel-ui/test-app/app/templates/index.gts b/packages/boxel-ui/test-app/app/templates/index.gts
index 657806c98dd..9b4e8b04c40 100644
--- a/packages/boxel-ui/test-app/app/templates/index.gts
+++ b/packages/boxel-ui/test-app/app/templates/index.gts
@@ -18,7 +18,9 @@ import Themes, { type Theme } from '../themes/index';
 import IconsGrid from '../components/icons-grid';
 
 import {
+  CardContainer,
   BoxelSelect,
+  CopyButton,
   FieldContainer,
   Switch,
   BoxelContainer,
@@ -29,72 +31,250 @@ import formatComponentName from '../helpers/format-component-name';
 interface UsageComponent {
   title: string;
   component: ComponentLike;
+  importStatement: string;
+}
+
+// A handful of usage titles differ from the name the component is exported as.
+const EXPORT_NAME_OVERRIDES: Record<string, string> = {
+  Container: 'BoxelContainer',
+  Dropdown: 'BoxelDropdown',
+  Input: 'BoxelInput',
+  InputGroup: 'BoxelInputGroup',
+  MultiSelect: 'BoxelMultiSelect',
+  Select: 'BoxelSelect',
+  Tag: 'BoxelTag',
+  EntityIconDisplay: 'EntityDisplayWithIcon',
+  EntityThumbnailDisplay: 'EntityDisplayWithThumbnail',
+  Kanban: 'DndKanbanBoard',
+};
+
+function importStatementFor(title: string): string {
+  let exportName = EXPORT_NAME_OVERRIDES[title] ?? title;
+  return `import { ${exportName} } from '@cardstack/boxel-ui/components';`;
 }
 
 class IndexComponent extends Component {
   <template>
     {{pageTitle 'Boxel Components'}}
-    <BasicDropdownWormhole />
-
-    <h1 class='boxel-sr-only'>Boxel Components Documentation</h1>
-    <FreestyleGuide
-      class='boxel-freestyle-guide'
-      @title='Boxel UI Components'
-      @subtitle='Living Component Documentation'
+    <CardContainer
+      class='boxel-freestyle-guide-container'
+      @isThemed={{true}}
       style={{this.theme.styles}}
     >
-      <BoxelContainer @display='flex'>
-        <FieldContainer @label='Theme' @tag='label'>
-          <BoxelSelect
-            class='theme-selector'
-            @placeholder='Select Theme'
-            @selected={{this.theme}}
-            @options={{this.themes}}
-            @onChange={{this.selectTheme}}
-            as |theme|
-          >
-            {{theme.name}}
-          </BoxelSelect>
-        </FieldContainer>
-        <FieldContainer @label='Cycle Themes' @tag='label'>
-          <Switch
-            @label='Cycle Themes'
-            @isEnabled={{this.isCycleThemesEnabled}}
-            @onChange={{this.toggleCycling}}
-          />
-        </FieldContainer>
-      </BoxelContainer>
-
-      <FreestyleSection
-        @name='Components'
-        class='freestyle-components-section'
-        as |Section|
-      >
-        {{#each this.usageComponents as |c|}}
-          <Section.subsection @name={{formatComponentName c.title}}>
-            <c.component />
-          </Section.subsection>
-        {{/each}}
-      </FreestyleSection>
-      <FreestyleSection
-        @name='boxel-icons'
-        class='freestyle-components-section'
+      <BasicDropdownWormhole />
+
+      <h1 class='boxel-sr-only'>Boxel Components Documentation</h1>
+      <FreestyleGuide
+        class='boxel-freestyle-guide'
+        @title='Boxel UI Components'
+        @subtitle='Living Component Documentation'
       >
-        <IconsGrid />
-      </FreestyleSection>
-    </FreestyleGuide>
+        <BoxelContainer class='boxel-freestyle-theme-settings' @display='flex'>
+          <FieldContainer @label='Theme' @tag='label'>
+            <BoxelSelect
+              class='boxel-freestyle-theme-selector'
+              @placeholder='Select Theme'
+              @selected={{this.theme}}
+              @options={{this.themes}}
+              @onChange={{this.selectTheme}}
+              as |theme|
+            >
+              {{theme.name}}
+            </BoxelSelect>
+          </FieldContainer>
+          <FieldContainer @label='Cycle Themes' @tag='label'>
+            <Switch
+              @label='Cycle Themes'
+              @isEnabled={{this.isCycleThemesEnabled}}
+              @onChange={{this.toggleCycling}}
+            />
+          </FieldContainer>
+        </BoxelContainer>
+        <FreestyleSection @name='Icons' class='freestyle-components-section'>
+          <IconsGrid />
+        </FreestyleSection>
+        <FreestyleSection
+          @name='Components'
+          class='freestyle-components-section'
+          as |Section|
+        >
+          {{#each this.usageComponents as |c|}}
+            <Section.subsection @name={{formatComponentName c.title}}>
+              <BoxelContainer>
+                <div class='subsection-import'>
+                  <code
+                    class='subsection-import-code'
+                  >{{c.importStatement}}</code>
+                  <CopyButton
+                    @textToCopy={{c.importStatement}}
+                    @tooltipText='Copy import'
+                    @ariaLabel='Copy import statement'
+                    @size='small'
+                  />
+                </div>
+                <CardContainer
+                  class='subsection-card'
+                  @displayBoundaries={{true}}
+                >
+                  <c.component />
+                </CardContainer>
+              </BoxelContainer>
+            </Section.subsection>
+          {{/each}}
+        </FreestyleSection>
+      </FreestyleGuide>
+    </CardContainer>
     <style scoped>
-      .boxel-freestyle-guide {
-        font-family: var(--font-sans, var(--boxel-font-family));
-        font-size: var(--boxel-body-font-size, 0.875rem);
-        line-height: var(--boxel-body-line-height, calc(18 / 13));
+      .boxel-freestyle-guide-container {
+        border-radius: 0;
+      }
+      .boxel-freestyle-theme-settings {
+        --boxel-container-gap: 0;
+        --boxel-container-padding: 0;
+        --boxel-form-control-height: 30px;
+        position: absolute;
+        top: var(--boxel-sp-lg);
+        right: var(--boxel-sp-4xl);
+        width: min-content;
       }
-      .theme-selector {
+      .boxel-freestyle-theme-selector {
         min-width: 10rem;
       }
+      .subsection-import {
+        display: flex;
+        align-items: center;
+        gap: var(--boxel-sp-xs);
+        margin-bottom: var(--boxel-sp-sm);
+        padding: var(--boxel-sp-4xs) var(--boxel-sp-4xs) var(--boxel-sp-4xs)
+          var(--boxel-sp-xs);
+        background-color: color-mix(in oklab, var(--muted) 70%, transparent);
+        border: 1px solid color-mix(in oklab, var(--border) 60%, transparent);
+        border-radius: var(--theme-radius, var(--boxel-border-radius));
+      }
+      .subsection-import-code {
+        flex: 1;
+        overflow-x: auto;
+        font-family: var(--font-mono);
+        font-size: 0.8125rem;
+        line-height: 1.5;
+        white-space: nowrap;
+        color: color-mix(in oklab, var(--foreground) 85%, transparent);
+      }
+      .subsection-card {
+        background-color: var(--card);
+        color: var(--card-foreground);
+      }
+      .FreestyleGuide {
+        display: grid;
+      }
+      .FreestyleUsage {
+        --radius: var(--theme-radius);
+        --border-color: var(--border);
+      }
+      .FreestyleGuide-header {
+        position: relative;
+        padding: var(--boxel-sp-xl) var(--boxel-sp-xl) var(--boxel-sp-lg);
+        background-image: linear-gradient(
+          135deg,
+          var(--muted) 0%,
+          color-mix(in oklab, var(--muted) 60%, var(--background)) 100%
+        );
+        color: var(--foreground);
+        border-bottom: 1px solid
+          color-mix(in oklab, var(--border) 60%, transparent);
+      }
+      .FreestyleGuide-title {
+        margin: 0;
+        font-size: 1.75rem;
+        line-height: 1.15;
+      }
+      .FreestyleGuide-subtitle {
+        margin-top: var(--boxel-sp-4xs);
+        font-size: 0.875rem;
+        font-weight: 500;
+        letter-spacing: 0.06em;
+        text-transform: uppercase;
+        color: color-mix(in oklab, var(--foreground) 60%, transparent);
+      }
+      .FreestyleGuide-body {
+        height: 100%;
+        overflow: hidden;
+        background-color: inherit;
+      }
+      .FreestyleGuide-nav {
+        height: 100%;
+        background-color: var(--sidebar);
+        color: var(--sidebar-foreground);
+        border-right-color: var(--sidebar-border);
+      }
+      .FreestyleMenu-itemLink,
+      .FreestyleMenu-submenuItemLink {
+        color: inherit;
+      }
+      .FreestyleMenu-itemLink.active,
+      .FreestyleMenu-submenuItemLink.active {
+        background-color: var(--sidebar-foreground);
+        color: var(--sidebar);
+        font-weight: normal;
+      }
+      .FreestyleMenu-itemLink:hover,
+      .FreestyleMenu-submenuItemLink:hover {
+        background-color: color-mix(
+          in oklab,
+          var(--sidebar-foreground) 10%,
+          transparent
+        );
+        color: var(--sidebar-foreground);
+      }
+      .FreestyleMenu-itemLink.active:hover,
+      .FreestyleMenu-submenuItemLink.active:hover {
+        background-color: color-mix(
+          in oklab,
+          var(--sidebar-foreground) 90%,
+          transparent
+        );
+        color: var(--sidebar);
+      }
+      .FreestyleUsage + .FreestyleUsage {
+        border-top: 1px solid var(--border);
+      }
+      .FreestyleUsage:last-child {
+        border-bottom: unset;
+      }
       .FreestyleUsageCssVar-name {
         width: 40%;
       }
+      .FreestyleGuide-title,
+      .FreestyleUsage-name {
+        font-weight: 600;
+      }
+      .FreestyleSection-name {
+        margin-bottom: var(--boxel-sp);
+        padding-bottom: var(--boxel-sp-xs);
+        font-size: 1.375rem;
+        font-weight: 600;
+        line-height: 1.2;
+        border-bottom: 1px solid
+          color-mix(in oklab, var(--border) 60%, transparent);
+      }
+      .FreestyleSubsection-name {
+        font-family: var(--font-mono);
+        font-size: 1.0625rem;
+        font-weight: 600;
+        line-height: 1.3;
+      }
+      .FreestyleUsage-name {
+        margin-block: var(--boxel-sp-lg);
+        font-size: 1.0625rem;
+        line-height: 1.3;
+      }
+      .FreestyleUsage-name {
+        color: var(--foreground);
+      }
+      .FreestyleUsage-description {
+        line-height: 1.55;
+        color: color-mix(in oklab, var(--foreground) 75%, transparent);
+      }
       .FreestyleUsage-preview {
         --radius: var(--theme-radius, var(--boxel-border-radius));
 
@@ -102,6 +282,32 @@ class IndexComponent extends Component {
         background-color: var(--background, var(--boxel-light));
         border-radius: 4px;
       }
+      .FreestyleUsage-apiTable tr:nth-child(even),
+      .FreestyleUsage-cssVarsTable tr:nth-child(even) {
+        background-color: color-mix(
+          in oklab,
+          var(--background) 90%,
+          var(--foreground)
+        );
+      }
+      .FreestyleUsage-apiTable tr,
+      .FreestyleUsage-cssVarsTable tr {
+        border-bottom-color: color-mix(
+          in oklab,
+          var(--border) 50%,
+          transparent
+        );
+      }
+      .u-codePill {
+        background-color: var(--muted);
+        color: var(--muted-foreground);
+        font-family: var(--font-mono);
+      }
+      .FreestyleUsage-sourceContainer,
+      .FreestyleUsage-apiTable,
+      .FreestyleUsage-cssVarsTable {
+        margin-inline: unset;
+      }
     </style>
   </template>
 
@@ -111,6 +317,7 @@ class IndexComponent extends Component {
     return {
       title: name,
       component: c,
+      importStatement: importStatementFor(name as string),
     };
   }) as UsageComponent[];
 
diff --git a/packages/host/app/app.ts b/packages/host/app/app.ts
index ac34f54d7b3..c30c1c0afc7 100644
--- a/packages/host/app/app.ts
+++ b/packages/host/app/app.ts
@@ -10,6 +10,7 @@ import config from './config/environment';
 import '@cardstack/boxel-ui/styles/global.css';
 import '@cardstack/boxel-ui/styles/fonts.css';
 import '@cardstack/boxel-ui/styles/variables.css';
+import '@cardstack/boxel-ui/styles/theme.css';
 import 'katex/dist/katex.min.css';
 
 import compatModules from '@embroider/virtual/compat-modules';