docs(theme): update "Custom theme" example (#2260)

Closes #1525

Author: metonym

docs/src/pages/components/Theme.svx

@@ -33,7 +33,11 @@ Set `persist` to `true` to save the theme preference in [localStorage](https://d
 
 ## Custom theme
 
-Override default Carbon theme tokens by providing custom key-value pairs in the `tokens` prop. Refer to the [Carbon website](https://carbondesignsystem.com/guidelines/themes/overview#customizing-a-theme) for guidance on customizing themes.
+Override default Carbon theme tokens using the `tokens` prop.
+
+**Understanding token usage:** The Theme component sets CSS custom properties via `--cds-{token}`. However, not all token names directly map to component styles. Components often use **semantic tokens** (like `interactive-01`) rather than component-specific tokens (like `button-primary`).
+
+For example, primary buttons use `interactive-01` for background color, `hover-primary` for hover state, and `active-primary` for active state. Both token types exist in the system but serve different purposes. Refer to the component CSS or Carbon Design System documentation to understand which tokens affect specific components.
 
 <FileSource src="/framed/Theme/ThemeTokens" />
 

docs/src/pages/framed/Theme/ThemeTokens.svelte

@@ -1,14 +1,77 @@
 <script>
-  import { Theme, Button } from "carbon-components-svelte";
+  import {
+    Theme,
+    Button,
+    Link,
+    Tag,
+    TextInput,
+    Checkbox,
+    Toggle,
+    Tile,
+    InlineNotification,
+  } from "carbon-components-svelte";
 </script>
 
 <Theme
   theme="g90"
   tokens={{
-    "interactive-01": "#d02670",
-    "hover-primary": "#ee5396",
-    "active-primary": "#9f1853",
+    // Interactive elements
+    "interactive-01": "#d02670", // Primary button background
+    "hover-primary": "#ee5396", // Primary button hover
+    "active-primary": "#9f1853", // Primary button active
+    "interactive-02": "#6f6f6f", // Secondary button background
+    "hover-secondary": "#5e5e5e", // Secondary button hover
+
+    // Links
+    "link-01": "#ff6eb3", // Link text color
+
+    // Tags
+    "tag-background-blue": "#4a1942", // Tag background
+    "tag-color-blue": "#ffb3d9", // Tag text color
+
+    // Form elements
+    "field-01": "#2d2d2d", // Input field background
+    "ui-01": "#2d2d2d", // Tile background
+    focus: "#ff6eb3", // Focus indicator color
+
+    // Text colors
+    "text-01": "#ffffff", // Primary text
+    "text-02": "#c6c6c6", // Secondary text
+
+    // Notification colors
+    "support-04": "#a855f7", // Info notification color
   }}
 />
 
-<Button>Primary button</Button>
+<div style="display: flex; flex-direction: column; gap: 1rem;">
+  <div>
+    <Button>Primary button</Button>
+    <Button kind="secondary">Secondary button</Button>
+  </div>
+
+  <div>
+    <Link href="#example">Themed link</Link>
+  </div>
+
+  <div>
+    <Tag type="blue">Themed tag</Tag>
+  </div>
+
+  <TextInput labelText="Text input" placeholder="Enter text..." />
+
+  <Checkbox labelText="Checkbox with themed focus" />
+
+  <Toggle labelText="Toggle with themed colors" />
+
+  <Tile>
+    <p>Tile with themed background</p>
+  </Tile>
+
+  <InlineNotification
+    kind="info"
+    title="Info notification"
+    subtitle="With themed colors"
+    hideCloseButton
+    lowContrast
+  />
+</div>