@aleph-alpha/ui-library 1.12.0 → 1.14.0

package/src/theme/Theme.stories.ts

@@ -0,0 +1,309 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite';
+import { defineComponent, h } from 'vue';
+
+const ThemePlaceholder = defineComponent({
+  name: 'ThemePlaceholder',
+  render() {
+    return h('div');
+  },
+});
+
+const meta: Meta<typeof ThemePlaceholder> = {
+  title: 'Theme/Content',
+  component: ThemePlaceholder,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ThemePlaceholder>;
+
+const copyScript = `
+  function copyToClipboard(text, el) {
+    navigator.clipboard.writeText(text).then(() => {
+      el.classList.add('copied');
+      setTimeout(() => el.classList.remove('copied'), 1500);
+    });
+  }
+`;
+
+/**
+ * Text colors for content displayed on surface backgrounds.
+ * Use these for headings, body text, links, and UI labels on standard backgrounds.
+ * Includes primary, secondary, tertiary, muted, link, and inverse variants.
+ */
+export const OnSurface: Story = {
+  render: () => ({
+    template: `
+      <div class="p-8 bg-white dark:bg-background min-h-screen">
+        <style>
+          .copy-btn { cursor: pointer; transition: all 0.15s; }
+          .copy-btn:hover { background: rgba(0,0,0,0.05); }
+          .copy-btn.copied { background: #22c55e22; }
+          .copy-btn.copied::after { content: ' ✓'; color: #22c55e; }
+        </style>
+        <script>${copyScript}</script>
+        
+        <div class="mb-6">
+          <h2 class="text-xl font-bold text-content-on-surface-primary mb-1">on-surface</h2>
+          <p class="text-sm text-content-on-surface-muted">Text colors for content on surface backgrounds. Click class name to copy.</p>
+        </div>
+        
+        <div class="flex flex-wrap gap-6">
+          <div class="flex flex-col items-center gap-1.5">
+            <div class="w-16 h-16 rounded-md bg-background-surface-secondary border border-border-surface-default flex items-center justify-center">
+              <span class="text-content-on-surface-primary text-2xl font-bold">Aa</span>
+            </div>
+            <div class="text-center">
+              <span class="text-xs text-content-on-surface-primary block font-medium">primary</span>
+              <code class="copy-btn text-[10px] text-content-on-surface-muted block mt-0.5 px-1 py-0.5 rounded" onclick="copyToClipboard('text-content-on-surface-primary', this)">text-content-on-surface-primary</code>
+            </div>
+          </div>
+          
+          <div class="flex flex-col items-center gap-1.5">
+            <div class="w-16 h-16 rounded-md bg-background-surface-secondary border border-border-surface-default flex items-center justify-center">
+              <span class="text-content-on-surface-secondary text-2xl font-bold">Aa</span>
+            </div>
+            <div class="text-center">
+              <span class="text-xs text-content-on-surface-primary block font-medium">secondary</span>
+              <code class="copy-btn text-[10px] text-content-on-surface-muted block mt-0.5 px-1 py-0.5 rounded" onclick="copyToClipboard('text-content-on-surface-secondary', this)">text-content-on-surface-secondary</code>
+            </div>
+          </div>
+          
+          <div class="flex flex-col items-center gap-1.5">
+            <div class="w-16 h-16 rounded-md bg-background-surface-secondary border border-border-surface-default flex items-center justify-center">
+              <span class="text-content-on-surface-tertiary text-2xl font-bold">Aa</span>
+            </div>
+            <div class="text-center">
+              <span class="text-xs text-content-on-surface-primary block font-medium">tertiary</span>
+              <code class="copy-btn text-[10px] text-content-on-surface-muted block mt-0.5 px-1 py-0.5 rounded" onclick="copyToClipboard('text-content-on-surface-tertiary', this)">text-content-on-surface-tertiary</code>
+            </div>
+          </div>
+          
+          <div class="flex flex-col items-center gap-1.5">
+            <div class="w-16 h-16 rounded-md bg-background-surface-secondary border border-border-surface-default flex items-center justify-center">
+              <span class="text-content-on-surface-muted text-2xl font-bold">Aa</span>
+            </div>
+            <div class="text-center">
+              <span class="text-xs text-content-on-surface-primary block font-medium">muted</span>
+              <code class="copy-btn text-[10px] text-content-on-surface-muted block mt-0.5 px-1 py-0.5 rounded" onclick="copyToClipboard('text-content-on-surface-muted', this)">text-content-on-surface-muted</code>
+            </div>
+          </div>
+          
+          <div class="flex flex-col items-center gap-1.5">
+            <div class="w-16 h-16 rounded-md bg-background-surface-secondary border border-border-surface-default flex items-center justify-center">
+              <span class="text-content-on-surface-link text-2xl font-bold">Aa</span>
+            </div>
+            <div class="text-center">
+              <span class="text-xs text-content-on-surface-primary block font-medium">link</span>
+              <code class="copy-btn text-[10px] text-content-on-surface-muted block mt-0.5 px-1 py-0.5 rounded" onclick="copyToClipboard('text-content-on-surface-link', this)">text-content-on-surface-link</code>
+            </div>
+          </div>
+          
+          <div class="flex flex-col items-center gap-1.5">
+            <div class="w-16 h-16 rounded-md bg-background-surface-inverse border border-border-surface-default flex items-center justify-center">
+              <span class="text-content-on-surface-inverse text-2xl font-bold">Aa</span>
+            </div>
+            <div class="text-center">
+              <span class="text-xs text-content-on-surface-primary block font-medium">inverse</span>
+              <code class="copy-btn text-[10px] text-content-on-surface-muted block mt-0.5 px-1 py-0.5 rounded" onclick="copyToClipboard('text-content-on-surface-inverse', this)">text-content-on-surface-inverse</code>
+            </div>
+          </div>
+        </div>
+      </div>
+    `,
+  }),
+};
+
+/**
+ * Text colors for button labels and icons.
+ * Use these to ensure proper contrast on primary, secondary, no-fill, and danger button backgrounds.
+ */
+export const OnButton: Story = {
+  render: () => ({
+    template: `
+      <div class="p-8 bg-white dark:bg-background min-h-screen">
+        <style>
+          .copy-btn { cursor: pointer; transition: all 0.15s; }
+          .copy-btn:hover { background: rgba(0,0,0,0.05); }
+          .copy-btn.copied { background: #22c55e22; }
+          .copy-btn.copied::after { content: ' ✓'; color: #22c55e; }
+        </style>
+        <script>${copyScript}</script>
+        
+        <div class="mb-6">
+          <h2 class="text-xl font-bold text-content-on-surface-primary mb-1">on-button</h2>
+          <p class="text-sm text-content-on-surface-muted">Text colors for content on button backgrounds. Click class name to copy.</p>
+        </div>
+        
+        <div class="flex flex-wrap gap-6">
+          <div class="flex flex-col items-center gap-1.5">
+            <div class="w-16 h-16 rounded-md bg-background-button-primary-button border border-border-surface-default flex items-center justify-center">
+              <span class="text-content-on-button-primary-button text-2xl font-bold">Aa</span>
+            </div>
+            <div class="text-center">
+              <span class="text-xs text-content-on-surface-primary block font-medium">primary-button</span>
+              <code class="copy-btn text-[10px] text-content-on-surface-muted block mt-0.5 px-1 py-0.5 rounded" onclick="copyToClipboard('text-content-on-button-primary-button', this)">text-content-on-button-primary-button</code>
+            </div>
+          </div>
+          
+          <div class="flex flex-col items-center gap-1.5">
+            <div class="w-16 h-16 rounded-md bg-background-button-secondary-button border border-border-surface-default flex items-center justify-center">
+              <span class="text-content-on-button-secondary-button text-2xl font-bold">Aa</span>
+            </div>
+            <div class="text-center">
+              <span class="text-xs text-content-on-surface-primary block font-medium">secondary-button</span>
+              <code class="copy-btn text-[10px] text-content-on-surface-muted block mt-0.5 px-1 py-0.5 rounded" onclick="copyToClipboard('text-content-on-button-secondary-button', this)">text-content-on-button-secondary-button</code>
+            </div>
+          </div>
+          
+          <div class="flex flex-col items-center gap-1.5">
+            <div class="w-16 h-16 rounded-md bg-background-surface-secondary border border-border-surface-default flex items-center justify-center">
+              <span class="text-content-on-button-no-fill-button text-2xl font-bold">Aa</span>
+            </div>
+            <div class="text-center">
+              <span class="text-xs text-content-on-surface-primary block font-medium">no-fill-button</span>
+              <code class="copy-btn text-[10px] text-content-on-surface-muted block mt-0.5 px-1 py-0.5 rounded" onclick="copyToClipboard('text-content-on-button-no-fill-button', this)">text-content-on-button-no-fill-button</code>
+            </div>
+          </div>
+          
+          <div class="flex flex-col items-center gap-1.5">
+            <div class="w-16 h-16 rounded-md bg-background-button-danger-button border border-border-surface-default flex items-center justify-center">
+              <span class="text-content-on-button-danger-button text-2xl font-bold">Aa</span>
+            </div>
+            <div class="text-center">
+              <span class="text-xs text-content-on-surface-primary block font-medium">danger-button</span>
+              <code class="copy-btn text-[10px] text-content-on-surface-muted block mt-0.5 px-1 py-0.5 rounded" onclick="copyToClipboard('text-content-on-button-danger-button', this)">text-content-on-button-danger-button</code>
+            </div>
+          </div>
+        </div>
+      </div>
+    `,
+  }),
+};
+
+/**
+ * Text colors for content on accent-colored backgrounds.
+ * Use these for badges, chips, highlights, or selected states with accent backgrounds.
+ */
+export const OnAccent: Story = {
+  render: () => ({
+    template: `
+      <div class="p-8 bg-white dark:bg-background min-h-screen">
+        <style>
+          .copy-btn { cursor: pointer; transition: all 0.15s; }
+          .copy-btn:hover { background: rgba(0,0,0,0.05); }
+          .copy-btn.copied { background: #22c55e22; }
+          .copy-btn.copied::after { content: ' ✓'; color: #22c55e; }
+        </style>
+        <script>${copyScript}</script>
+        
+        <div class="mb-6">
+          <h2 class="text-xl font-bold text-content-on-surface-primary mb-1">on-accent</h2>
+          <p class="text-sm text-content-on-surface-muted">Text colors for content on accent backgrounds. Click class name to copy.</p>
+        </div>
+        
+        <div class="flex flex-wrap gap-6">
+          <div class="flex flex-col items-center gap-1.5">
+            <div class="w-16 h-16 rounded-md bg-background-accent-default border border-border-surface-default flex items-center justify-center">
+              <span class="text-content-on-accent-default text-2xl font-bold">Aa</span>
+            </div>
+            <div class="text-center">
+              <span class="text-xs text-content-on-surface-primary block font-medium">default</span>
+              <code class="copy-btn text-[10px] text-content-on-surface-muted block mt-0.5 px-1 py-0.5 rounded" onclick="copyToClipboard('text-content-on-accent-default', this)">text-content-on-accent-default</code>
+            </div>
+          </div>
+          
+          <div class="flex flex-col items-center gap-1.5">
+            <div class="w-16 h-16 rounded-md bg-background-accent-soft border border-border-surface-default flex items-center justify-center">
+              <span class="text-content-on-accent-soft text-2xl font-bold">Aa</span>
+            </div>
+            <div class="text-center">
+              <span class="text-xs text-content-on-surface-primary block font-medium">soft</span>
+              <code class="copy-btn text-[10px] text-content-on-surface-muted block mt-0.5 px-1 py-0.5 rounded" onclick="copyToClipboard('text-content-on-accent-soft', this)">text-content-on-accent-soft</code>
+            </div>
+          </div>
+        </div>
+      </div>
+    `,
+  }),
+};
+
+/**
+ * Semantic text colors for status indicators like success, warning, error, info, and neutral.
+ * Use these for validation messages, alerts, notifications, and status badges.
+ */
+export const OnStatus: Story = {
+  render: () => ({
+    template: `
+      <div class="p-8 bg-white dark:bg-background min-h-screen">
+        <style>
+          .copy-btn { cursor: pointer; transition: all 0.15s; }
+          .copy-btn:hover { background: rgba(0,0,0,0.05); }
+          .copy-btn.copied { background: #22c55e22; }
+          .copy-btn.copied::after { content: ' ✓'; color: #22c55e; }
+        </style>
+        <script>${copyScript}</script>
+        
+        <div class="mb-6">
+          <h2 class="text-xl font-bold text-content-on-surface-primary mb-1">on-status</h2>
+          <p class="text-sm text-content-on-surface-muted">Text colors for status indicators. Click class name to copy.</p>
+        </div>
+        
+        <div class="flex flex-wrap gap-6">
+          <div class="flex flex-col items-center gap-1.5">
+            <div class="w-16 h-16 rounded-md bg-background-surface-secondary border border-border-surface-default flex items-center justify-center">
+              <span class="text-content-on-status-success text-2xl font-bold">Aa</span>
+            </div>
+            <div class="text-center">
+              <span class="text-xs text-content-on-surface-primary block font-medium">success</span>
+              <code class="copy-btn text-[10px] text-content-on-surface-muted block mt-0.5 px-1 py-0.5 rounded" onclick="copyToClipboard('text-content-on-status-success', this)">text-content-on-status-success</code>
+            </div>
+          </div>
+          
+          <div class="flex flex-col items-center gap-1.5">
+            <div class="w-16 h-16 rounded-md bg-background-surface-secondary border border-border-surface-default flex items-center justify-center">
+              <span class="text-content-on-status-warning text-2xl font-bold">Aa</span>
+            </div>
+            <div class="text-center">
+              <span class="text-xs text-content-on-surface-primary block font-medium">warning</span>
+              <code class="copy-btn text-[10px] text-content-on-surface-muted block mt-0.5 px-1 py-0.5 rounded" onclick="copyToClipboard('text-content-on-status-warning', this)">text-content-on-status-warning</code>
+            </div>
+          </div>
+          
+          <div class="flex flex-col items-center gap-1.5">
+            <div class="w-16 h-16 rounded-md bg-background-surface-secondary border border-border-surface-default flex items-center justify-center">
+              <span class="text-content-on-status-error text-2xl font-bold">Aa</span>
+            </div>
+            <div class="text-center">
+              <span class="text-xs text-content-on-surface-primary block font-medium">error</span>
+              <code class="copy-btn text-[10px] text-content-on-surface-muted block mt-0.5 px-1 py-0.5 rounded" onclick="copyToClipboard('text-content-on-status-error', this)">text-content-on-status-error</code>
+            </div>
+          </div>
+          
+          <div class="flex flex-col items-center gap-1.5">
+            <div class="w-16 h-16 rounded-md bg-background-surface-secondary border border-border-surface-default flex items-center justify-center">
+              <span class="text-content-on-status-info text-2xl font-bold">Aa</span>
+            </div>
+            <div class="text-center">
+              <span class="text-xs text-content-on-surface-primary block font-medium">info</span>
+              <code class="copy-btn text-[10px] text-content-on-surface-muted block mt-0.5 px-1 py-0.5 rounded" onclick="copyToClipboard('text-content-on-status-info', this)">text-content-on-status-info</code>
+            </div>
+          </div>
+          
+          <div class="flex flex-col items-center gap-1.5">
+            <div class="w-16 h-16 rounded-md bg-background-surface-secondary border border-border-surface-default flex items-center justify-center">
+              <span class="text-content-on-status-neutral text-2xl font-bold">Aa</span>
+            </div>
+            <div class="text-center">
+              <span class="text-xs text-content-on-surface-primary block font-medium">neutral</span>
+              <code class="copy-btn text-[10px] text-content-on-surface-muted block mt-0.5 px-1 py-0.5 rounded" onclick="copyToClipboard('text-content-on-status-neutral', this)">text-content-on-status-neutral</code>
+            </div>
+          </div>
+        </div>
+      </div>
+    `,
+  }),
+};

package/src/theme/Typography.stories.ts

@@ -0,0 +1,230 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite';
+import { defineComponent, h } from 'vue';
+
+const ThemePlaceholder = defineComponent({
+  name: 'ThemePlaceholder',
+  render() {
+    return h('div');
+  },
+});
+
+const meta: Meta<typeof ThemePlaceholder> = {
+  title: 'Theme/Typography',
+  component: ThemePlaceholder,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof ThemePlaceholder>;
+
+const copyScript = `
+  function copyToClipboard(text, el) {
+    navigator.clipboard.writeText(text).then(() => {
+      el.classList.add('copied');
+      setTimeout(() => el.classList.remove('copied'), 1500);
+    });
+  }
+`;
+
+/**
+ * Heading typography styles from h1 to h6.
+ * Use these for page titles, section headings, and content hierarchy.
+ */
+export const Headings: Story = {
+  render: () => ({
+    template: `
+      <div class="p-8 bg-white dark:bg-background min-h-screen">
+        <style>
+          .copy-btn { cursor: pointer; transition: all 0.15s; }
+          .copy-btn:hover { background: rgba(0,0,0,0.05); }
+          .copy-btn.copied { background: #22c55e22; }
+          .copy-btn.copied::after { content: ' ✓'; color: #22c55e; }
+        </style>
+        <script>${copyScript}</script>
+        
+        <div class="mb-8">
+          <h2 class="text-xl font-bold text-content-on-surface-primary mb-1">Headings</h2>
+          <p class="text-sm text-content-on-surface-muted">Heading styles for content hierarchy. Click class name to copy.</p>
+        </div>
+        
+        <div class="space-y-6">
+          <div class="flex items-baseline gap-4 pb-4 border-b border-border-surface-default">
+            <code class="copy-btn text-xs text-content-on-surface-muted w-24 flex-shrink-0 px-1 py-0.5 rounded" onclick="copyToClipboard('text-4xl font-bold', this)">text-4xl font-bold</code>
+            <span class="text-4xl font-bold text-content-on-surface-primary">Heading 1 — The quick brown fox</span>
+          </div>
+          
+          <div class="flex items-baseline gap-4 pb-4 border-b border-border-surface-default">
+            <code class="copy-btn text-xs text-content-on-surface-muted w-24 flex-shrink-0 px-1 py-0.5 rounded" onclick="copyToClipboard('text-3xl font-bold', this)">text-3xl font-bold</code>
+            <span class="text-3xl font-bold text-content-on-surface-primary">Heading 2 — The quick brown fox</span>
+          </div>
+          
+          <div class="flex items-baseline gap-4 pb-4 border-b border-border-surface-default">
+            <code class="copy-btn text-xs text-content-on-surface-muted w-24 flex-shrink-0 px-1 py-0.5 rounded" onclick="copyToClipboard('text-2xl font-bold', this)">text-2xl font-bold</code>
+            <span class="text-2xl font-bold text-content-on-surface-primary">Heading 3 — The quick brown fox</span>
+          </div>
+          
+          <div class="flex items-baseline gap-4 pb-4 border-b border-border-surface-default">
+            <code class="copy-btn text-xs text-content-on-surface-muted w-24 flex-shrink-0 px-1 py-0.5 rounded" onclick="copyToClipboard('text-xl font-bold', this)">text-xl font-bold</code>
+            <span class="text-xl font-bold text-content-on-surface-primary">Heading 4 — The quick brown fox</span>
+          </div>
+          
+          <div class="flex items-baseline gap-4 pb-4 border-b border-border-surface-default">
+            <code class="copy-btn text-xs text-content-on-surface-muted w-24 flex-shrink-0 px-1 py-0.5 rounded" onclick="copyToClipboard('text-lg font-bold', this)">text-lg font-bold</code>
+            <span class="text-lg font-bold text-content-on-surface-primary">Heading 5 — The quick brown fox</span>
+          </div>
+          
+          <div class="flex items-baseline gap-4">
+            <code class="copy-btn text-xs text-content-on-surface-muted w-24 flex-shrink-0 px-1 py-0.5 rounded" onclick="copyToClipboard('text-base font-bold', this)">text-base font-bold</code>
+            <span class="text-base font-bold text-content-on-surface-primary">Heading 6 — The quick brown fox</span>
+          </div>
+        </div>
+      </div>
+    `,
+  }),
+};
+
+/**
+ * Body text styles for paragraphs and general content.
+ * Use base for standard text, sm for secondary content, lg for emphasized paragraphs.
+ */
+export const Body: Story = {
+  render: () => ({
+    template: `
+      <div class="p-8 bg-white dark:bg-background min-h-screen">
+        <style>
+          .copy-btn { cursor: pointer; transition: all 0.15s; }
+          .copy-btn:hover { background: rgba(0,0,0,0.05); }
+          .copy-btn.copied { background: #22c55e22; }
+          .copy-btn.copied::after { content: ' ✓'; color: #22c55e; }
+        </style>
+        <script>${copyScript}</script>
+        
+        <div class="mb-8">
+          <h2 class="text-xl font-bold text-content-on-surface-primary mb-1">Body</h2>
+          <p class="text-sm text-content-on-surface-muted">Body text styles for paragraphs and content. Click class name to copy.</p>
+        </div>
+        
+        <div class="space-y-6">
+          <div class="pb-4 border-b border-border-surface-default">
+            <code class="copy-btn text-xs text-content-on-surface-muted block mb-2 px-1 py-0.5 rounded w-fit" onclick="copyToClipboard('text-lg', this)">text-lg</code>
+            <p class="text-lg text-content-on-surface-primary">Large body text. The quick brown fox jumps over the lazy dog. This size is good for lead paragraphs or introductions.</p>
+          </div>
+          
+          <div class="pb-4 border-b border-border-surface-default">
+            <code class="copy-btn text-xs text-content-on-surface-muted block mb-2 px-1 py-0.5 rounded w-fit" onclick="copyToClipboard('text-base', this)">text-base</code>
+            <p class="text-base text-content-on-surface-primary">Base body text. The quick brown fox jumps over the lazy dog. This is the default paragraph size used for most content.</p>
+          </div>
+          
+          <div class="pb-4 border-b border-border-surface-default">
+            <code class="copy-btn text-xs text-content-on-surface-muted block mb-2 px-1 py-0.5 rounded w-fit" onclick="copyToClipboard('text-sm', this)">text-sm</code>
+            <p class="text-sm text-content-on-surface-primary">Small body text. The quick brown fox jumps over the lazy dog. Use for captions, helper text, or secondary information.</p>
+          </div>
+          
+          <div>
+            <code class="copy-btn text-xs text-content-on-surface-muted block mb-2 px-1 py-0.5 rounded w-fit" onclick="copyToClipboard('text-xs', this)">text-xs</code>
+            <p class="text-xs text-content-on-surface-primary">Extra small text. The quick brown fox jumps over the lazy dog. Use sparingly for labels, timestamps, or legal text.</p>
+          </div>
+        </div>
+      </div>
+    `,
+  }),
+};
+
+/**
+ * Label and UI text styles for form labels, buttons, and interactive elements.
+ * Includes medium and semibold weights for different emphasis levels.
+ */
+export const Labels: Story = {
+  render: () => ({
+    template: `
+      <div class="p-8 bg-white dark:bg-background min-h-screen">
+        <style>
+          .copy-btn { cursor: pointer; transition: all 0.15s; }
+          .copy-btn:hover { background: rgba(0,0,0,0.05); }
+          .copy-btn.copied { background: #22c55e22; }
+          .copy-btn.copied::after { content: ' ✓'; color: #22c55e; }
+        </style>
+        <script>${copyScript}</script>
+        
+        <div class="mb-8">
+          <h2 class="text-xl font-bold text-content-on-surface-primary mb-1">Labels</h2>
+          <p class="text-sm text-content-on-surface-muted">Label styles for forms and UI elements. Click class name to copy.</p>
+        </div>
+        
+        <div class="space-y-6">
+          <div class="flex items-center gap-4 pb-4 border-b border-border-surface-default">
+            <code class="copy-btn text-xs text-content-on-surface-muted w-32 flex-shrink-0 px-1 py-0.5 rounded" onclick="copyToClipboard('text-sm font-medium', this)">text-sm font-medium</code>
+            <span class="text-sm font-medium text-content-on-surface-primary">Form Label</span>
+          </div>
+          
+          <div class="flex items-center gap-4 pb-4 border-b border-border-surface-default">
+            <code class="copy-btn text-xs text-content-on-surface-muted w-32 flex-shrink-0 px-1 py-0.5 rounded" onclick="copyToClipboard('text-sm font-semibold', this)">text-sm font-semibold</code>
+            <span class="text-sm font-semibold text-content-on-surface-primary">Button Text</span>
+          </div>
+          
+          <div class="flex items-center gap-4 pb-4 border-b border-border-surface-default">
+            <code class="copy-btn text-xs text-content-on-surface-muted w-32 flex-shrink-0 px-1 py-0.5 rounded" onclick="copyToClipboard('text-xs font-medium', this)">text-xs font-medium</code>
+            <span class="text-xs font-medium text-content-on-surface-primary">Small Label</span>
+          </div>
+          
+          <div class="flex items-center gap-4">
+            <code class="copy-btn text-xs text-content-on-surface-muted w-32 flex-shrink-0 px-1 py-0.5 rounded" onclick="copyToClipboard('text-xs uppercase tracking-wider', this)">text-xs uppercase tracking-wider</code>
+            <span class="text-xs uppercase tracking-wider text-content-on-surface-primary">Overline Text</span>
+          </div>
+        </div>
+      </div>
+    `,
+  }),
+};
+
+/**
+ * Comprehensive article example showing typography hierarchy in context.
+ * Demonstrates how headings, body text, and other styles work together in real content.
+ */
+export const Article: Story = {
+  render: () => ({
+    template: `
+      <div class="p-8 bg-white dark:bg-background min-h-screen">
+        <div class="max-w-2xl mx-auto">
+          <article class="text-content-on-surface-primary">
+            <header class="mb-8">
+              <p class="text-xs uppercase tracking-wider text-content-on-surface-muted mb-2">Design System</p>
+              <h1 class="text-4xl font-bold mb-4">Building Consistent UI with Design Tokens</h1>
+              <p class="text-lg text-content-on-surface-secondary">A comprehensive guide to using design tokens for scalable and maintainable user interfaces.</p>
+            </header>
+            
+            <div class="space-y-6">
+              <p class="text-base">Design tokens are the visual design atoms of the design system — specifically, they are named entities that store visual design attributes. We use them in place of hard-coded values in order to maintain a scalable and consistent visual system for UI development.</p>
+              
+              <h2 class="text-2xl font-bold mt-8">Why Use Design Tokens?</h2>
+              
+              <p class="text-base">Using design tokens brings several benefits to your development workflow:</p>
+              
+              <ul class="list-disc list-inside space-y-2 text-base">
+                <li>Consistency across all UI components</li>
+                <li>Easy theming and brand customization</li>
+                <li>Single source of truth for design decisions</li>
+                <li>Simplified maintenance and updates</li>
+              </ul>
+              
+              <h3 class="text-xl font-bold mt-6">Token Categories</h3>
+              
+              <p class="text-base">Tokens are organized into categories based on their purpose:</p>
+              
+              <div class="bg-background-surface-muted p-4 rounded-md mt-4">
+                <p class="text-sm font-medium">Color tokens for backgrounds, text, and borders</p>
+                <p class="text-sm font-medium">Typography tokens for font sizes and weights</p>
+                <p class="text-sm font-medium">Spacing tokens for margins and padding</p>
+              </div>
+              
+              <p class="text-sm text-content-on-surface-muted mt-8">Last updated: February 2026</p>
+            </div>
+          </article>
+        </div>
+      </div>
+    `,
+  }),
+};