From c33b35ce701ad24af01f44613226b7c4e5ed78f3 Mon Sep 17 00:00:00 2001
From: gablisboa <gablisboa1@gmail.com>
Date: Wed, 27 May 2026 09:22:21 -0300
Subject: [PATCH 1/5] docs(foundations): reorganize token foundations stories

Restructure Storybook foundations docs and supporting data/components to better present spacing and typography foundations with updated architecture documentation.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .specs/_schema.json                           |   1 +
 .../components/ColorPlayground.vue            |  66 ++---
 .../foundations/components/ColorSwatch.vue    |   4 +-
 .../foundations/components/SpacingPreview.vue | 123 ++++-----
 .../components/TypographyPreview.vue          |  95 ++++---
 .../components/layout/ArchitectureDiagram.vue |  35 ++-
 .../foundations/composables/useViewport.js    |  17 +-
 .../storybook/src/foundations/data/spacing.js | 152 +----------
 .../src/foundations/data/typography.js        | 255 +-----------------
 .../src/stories/foundations/GetStarted.mdx    |  18 +-
 .../stories/foundations/Spacing.stories.js    | 103 -------
 .../stories/foundations/Typography.stories.js | 103 -------
 12 files changed, 209 insertions(+), 763 deletions(-)
 delete mode 100644 apps/storybook/src/stories/foundations/Spacing.stories.js
 delete mode 100644 apps/storybook/src/stories/foundations/Typography.stories.js

diff --git a/.specs/_schema.json b/.specs/_schema.json
index c854e0d3c..d9a1d5dfe 100644
--- a/.specs/_schema.json
+++ b/.specs/_schema.json
@@ -24,6 +24,7 @@
       "type": "string",
       "enum": [
         "actions",
+        "code",
         "content",
         "data",
         "feedback",
diff --git a/apps/storybook/src/foundations/components/ColorPlayground.vue b/apps/storybook/src/foundations/components/ColorPlayground.vue
index 5df3f490c..840661ff0 100644
--- a/apps/storybook/src/foundations/components/ColorPlayground.vue
+++ b/apps/storybook/src/foundations/components/ColorPlayground.vue
@@ -1,17 +1,17 @@
 <script setup>
 import { ref, computed, onMounted, onUnmounted } from 'vue';
-import { backgroundTokens, textTokens, borderTokens } from '../data/colors.js';
+import { playgroundColorTokens } from '../data/colors.js';
 
 const CATEGORIES = [
-  { key: 'background', label: 'Background', tokens: backgroundTokens, prefix: 'bg' },
-  { key: 'text',       label: 'Text',       tokens: textTokens,       prefix: 'text' },
-  { key: 'border',     label: 'Border',     tokens: borderTokens,     prefix: 'border' },
+  { key: 'theme', label: 'Theme', filter: (t) => t.category === 'theme' },
+  { key: 'background', label: 'Background', filter: (t) => t.category === 'background' },
+  { key: 'text', label: 'Text', filter: (t) => t.category === 'text' },
+  { key: 'border', label: 'Border', filter: (t) => t.category === 'border' },
 ];
 
-const selectedCategory = ref('background');
-const selectedTokenName = ref(backgroundTokens[0].name);
+const selectedCategory = ref('theme');
+const selectedTokenName = ref('primary');
 
-// Detect global theme from Storybook's theme addon (azion-light/azion-dark class)
 const isDark = ref(true);
 let observer = null;
 
@@ -22,38 +22,41 @@ function updateTheme() {
 
 onMounted(() => {
   updateTheme();
-  // Watch for class changes on document body or html element
   observer = new MutationObserver(updateTheme);
   observer.observe(document.documentElement, { attributes: true, attributeFilter: ['class'] });
   observer.observe(document.body, { attributes: true, attributeFilter: ['class'] });
+
+  const first = playgroundColorTokens.find((t) => t.name === 'primary') ?? playgroundColorTokens[0];
+  if (first) selectedTokenName.value = first.name;
 });
 
 onUnmounted(() => {
   observer?.disconnect();
 });
 
-const activeTokens = computed(() =>
-  CATEGORIES.find((c) => c.key === selectedCategory.value)?.tokens ?? []
-);
+const activeTokens = computed(() => {
+  const cat = CATEGORIES.find((c) => c.key === selectedCategory.value);
+  return cat ? playgroundColorTokens.filter(cat.filter) : playgroundColorTokens;
+});
 
-const selectedToken = computed(() =>
-  activeTokens.value.find((t) => t.name === selectedTokenName.value) ?? activeTokens.value[0]
+const selectedToken = computed(
+  () => activeTokens.value.find((t) => t.name === selectedTokenName.value) ?? activeTokens.value[0]
 );
 
 const currentHex = computed(() =>
   isDark.value ? selectedToken.value?.darkHex : selectedToken.value?.lightHex
 );
 
-const modeLabel = computed(() => isDark.value ? 'dark' : 'light');
+const modeLabel = computed(() => (isDark.value ? 'dark' : 'light'));
 
 const previewStyle = computed(() => {
   const hex = currentHex.value;
   if (!hex) return {};
   const cat = selectedCategory.value;
-  if (cat === 'background') return { backgroundColor: hex };
-  if (cat === 'text')       return { color: hex };
-  if (cat === 'border')     return { borderColor: hex, borderWidth: '2px', borderStyle: 'solid' };
-  return {};
+  if (cat === 'background' || cat === 'theme') return { backgroundColor: hex };
+  if (cat === 'text') return { color: hex };
+  if (cat === 'border') return { borderColor: hex, borderWidth: '2px', borderStyle: 'solid' };
+  return { backgroundColor: hex };
 });
 
 const previewTextStyle = computed(() => {
@@ -74,7 +77,6 @@ function onCategoryChange() {
   selectedTokenName.value = activeTokens.value[0]?.name ?? '';
 }
 
-// Track copied state
 const copiedKey = ref(null);
 let copyTimeout = null;
 
@@ -94,7 +96,6 @@ function isCopied(key) {
 
 <template>
   <div class="flex flex-col gap-6">
-    <!-- Controls ─────────────────────────────────────────────────────────── -->
     <div class="flex gap-5 items-end flex-wrap">
       <div class="flex flex-col gap-1.5">
         <label class="text-[10px] font-semibold uppercase tracking-wider text-muted">Category</label>
@@ -106,10 +107,15 @@ function isCopied(key) {
               'px-3.5 py-1.5 text-xs font-medium cursor-pointer bg-transparent transition-all duration-100',
               selectedCategory === cat.key
                 ? 'bg-primary text-white font-semibold'
-                : 'text-muted border-r border-default last:border-r-0'
+                : 'text-muted border-r border-default last:border-r-0',
             ]"
-            @click="selectedCategory = cat.key; onCategoryChange()"
-          >{{ cat.label }}</button>
+            @click="
+              selectedCategory = cat.key;
+              onCategoryChange();
+            "
+          >
+            {{ cat.label }}
+          </button>
         </div>
       </div>
 
@@ -126,17 +132,13 @@ function isCopied(key) {
       </div>
     </div>
 
-    <!-- Preview ───────────────────────────────────────────────────────────── -->
     <div class="flex gap-5 items-start flex-wrap">
       <div
         class="flex-1 min-w-[220px] min-h-[160px] rounded-[10px] flex items-center justify-center transition-all duration-200"
         :class="selectedCategory !== 'border' ? 'border border-default' : ''"
         :style="previewStyle"
       >
-        <span
-          class="font-code text-[15px] font-semibold"
-          :style="previewTextStyle"
-        >
+        <span class="font-code text-[15px] font-semibold" :style="previewTextStyle">
           {{ selectedToken?.tailwindClass }}
         </span>
       </div>
@@ -149,7 +151,7 @@ function isCopied(key) {
             @click="copyToClipboard(selectedToken?.tailwindClass, 'tw')"
           >
             <code class="font-code text-[11px] border bg-white/10 border-white/15 text-code px-1.5 py-0.5 rounded">{{ selectedToken?.tailwindClass }}</code>
-            <i :class="['pi text-[11px] opacity-0 group-hover:!opacity-50', isCopied('css') ? 'pi-check text-success' : 'pi-copy']" />
+            <i :class="['pi text-[11px] opacity-0 group-hover:!opacity-50', isCopied('tw') ? 'pi-check text-success' : 'pi-copy']" />
           </button>
         </div>
 
@@ -168,7 +170,7 @@ function isCopied(key) {
           <span class="text-[10px] font-semibold uppercase tracking-wider text-muted">Resolved ({{ modeLabel }})</span>
           <span class="flex items-center gap-1.5 flex-wrap">
             <span
-              class="w-3.5 h-3.5 rounded flex-shrink-0 border border-gray-500/30"
+              class="w-3.5 h-3.5 rounded flex-shrink-0 border border-default"
               :style="{ background: currentHex ?? 'transparent' }"
             />
             <code class="font-code text-[11px] border bg-white/10 border-white/15 text-code px-1.5 py-0.5 rounded">{{ currentHex }}</code>
@@ -184,13 +186,13 @@ function isCopied(key) {
           <span class="text-[10px] font-semibold uppercase tracking-wider text-muted">Light → Dark</span>
           <span class="flex items-center gap-1.5 flex-wrap">
             <span
-              class="w-3.5 h-3.5 rounded flex-shrink-0 border border-gray-500/30"
+              class="w-3.5 h-3.5 rounded flex-shrink-0 border border-default"
               :style="{ background: selectedToken?.lightHex ?? 'transparent' }"
             />
             <code class="font-code text-[11px] border bg-white/10 border-white/15 text-code px-1.5 py-0.5 rounded">{{ selectedToken?.lightHex }}</code>
             <span class="opacity-40 text-[11px]">→</span>
             <span
-              class="w-3.5 h-3.5 rounded flex-shrink-0 border border-gray-500/30"
+              class="w-3.5 h-3.5 rounded flex-shrink-0 border border-default"
               :style="{ background: selectedToken?.darkHex ?? 'transparent' }"
             />
             <code class="font-code text-[11px] border bg-white/10 border-white/15 text-code px-1.5 py-0.5 rounded">{{ selectedToken?.darkHex }}</code>
diff --git a/apps/storybook/src/foundations/components/ColorSwatch.vue b/apps/storybook/src/foundations/components/ColorSwatch.vue
index 003d9c7b7..e08e49a55 100644
--- a/apps/storybook/src/foundations/components/ColorSwatch.vue
+++ b/apps/storybook/src/foundations/components/ColorSwatch.vue
@@ -22,7 +22,7 @@ const labelColor = computed(() => {
 </script>
 
 <template>
-  <div class="flex flex-col rounded-md overflow-hidden border border-gray-500/15 flex-1 min-w-[60px] max-w-[88px] cursor-default">
+  <div class="flex flex-col rounded-md overflow-hidden border border-default flex-1 min-w-[60px] max-w-[88px] cursor-default">
     <div
       class="h-[52px] flex items-end px-1.5 py-1"
       :style="{ background: hex ?? 'transparent' }"
@@ -33,7 +33,7 @@ const labelColor = computed(() => {
       >{{ shade }}</span>
     </div>
     <div class="px-1.5 py-[5px] bg-black/25">
-      <span class="text-[9px] font-code text-gray-400 block break-all leading-tight">{{ hex }}</span>
+      <span class="text-[9px] font-code text-muted block break-all leading-tight">{{ hex }}</span>
     </div>
   </div>
 </template>
diff --git a/apps/storybook/src/foundations/components/SpacingPreview.vue b/apps/storybook/src/foundations/components/SpacingPreview.vue
index 82b926226..60cca1f01 100644
--- a/apps/storybook/src/foundations/components/SpacingPreview.vue
+++ b/apps/storybook/src/foundations/components/SpacingPreview.vue
@@ -1,20 +1,41 @@
 <script setup>
-import { ref } from 'vue';
+import { ref, computed } from 'vue';
 import { useViewport } from '../composables/useViewport.js';
+import { getActiveBreakpoint } from '../utils/from-tokens.js';
 
-defineProps({
-  /**
-   * Spacing token object:
-   * { name, category, label, property, description, desktop, tablet, mobile }
-   */
+const props = defineProps({
+  /** Token from spacings.data.js (via from-tokens.js) */
   token: { type: Object, required: true },
 });
 
 const { breakpoint } = useViewport();
 
+const BREAKPOINT_LABELS = {
+  _: 'Base',
+  sm: 'sm ≥640',
+  md: 'md ≥768',
+  lg: 'lg ≥1024',
+  xl: 'xl ≥1280',
+  '2xl': '2xl ≥1536',
+};
+
 const copiedKey = ref(null);
 let copyTimeout = null;
 
+const activeValue = computed(() => {
+  if (typeof window === 'undefined') return props.token.responsive._ ?? '';
+  const map = props.token.responsive;
+  const width = window.innerWidth;
+  const active = getActiveBreakpoint(width);
+  const order = ['_', 'sm', 'md', 'lg', 'xl', '2xl'];
+  const index = order.indexOf(active);
+  for (let i = index; i >= 0; i -= 1) {
+    const bp = order[i];
+    if (map[bp] !== undefined) return map[bp];
+  }
+  return '';
+});
+
 function copyToClipboard(text, key) {
   navigator.clipboard?.writeText(text).catch(() => {});
   copiedKey.value = key;
@@ -31,77 +52,57 @@ function isCopied(key) {
 
 <template>
   <div class="flex w-full flex-col gap-4 py-5 border-b border-subtle items-start last:border-b-0 sm:flex-row sm:gap-6">
-    <div class="flex flex-col w-full gap-1.5 sm:w-72 sm:flex-none">
+    <div class="flex flex-col w-full gap-1.5 sm:w-80 sm:flex-none">
       <p class="text-sm font-semibold text-default m-0">{{ token.label }}</p>
       <button
         class="inline-flex items-center gap-1.5 bg-none border-none p-0 cursor-pointer font-inherit group"
-        @click="copyToClipboard(token.name, token.name)"
-        :title="'Copy: ' + token.name"
+        @click="copyToClipboard(token.cssVar, token.name)"
+        :title="'Copy: ' + token.cssVar"
+      >
+        <code class="font-code text-[11px] bg-white/[0.07] border border-white/15 text-code px-1.5 py-0.5 rounded w-fit">{{ token.cssVar }}</code>
+        <i
+          :class="[
+            'pi text-[10px] transition-opacity duration-100',
+            isCopied(token.name) ? 'pi-check text-success' : 'pi-copy opacity-0 group-hover:opacity-50',
+          ]"
+        />
+      </button>
+      <button
+        class="inline-flex items-center gap-1.5 bg-none border-none p-0 cursor-pointer font-inherit group text-left"
+        @click="copyToClipboard(token.usageExample, token.name + '-usage')"
+        :title="'Copy usage'"
       >
-        <code class="font-code text-[11px] bg-white/[0.07] border border-white/15 text-code px-1.5 py-0.5 rounded w-fit">{{ token.name }}</code>
-        <i :class="[
-          'pi text-[10px] transition-opacity duration-100',
-          isCopied(token.name) ? 'pi-check text-success' : 'pi-copy opacity-0 group-hover:opacity-50'
-        ]" />
+        <code class="font-code text-[10px] text-muted">{{ token.usageExample }}</code>
       </button>
       <p class="text-xs text-muted m-0 mb-2 leading-relaxed">{{ token.description }}</p>
+      <p class="text-[10px] text-muted m-0 font-code">Source: packages/theme/src/tokens/semantic/spacings.data.js</p>
 
-      <div class="grid grid-cols-2 gap-x-3 gap-y-3 w-full m-0">
-        <div class="flex flex-col gap-0.5">
-          <span class="text-[9px] font-semibold uppercase tracking-wider text-muted">Property</span>
-          <span class="font-code text-[10px] text-muted">{{ token.property }}</span>
-        </div>
-        <div class="flex flex-col gap-0.5">
-          <span :class="['text-[9px] font-semibold uppercase tracking-wider', breakpoint === 'desktop' ? 'text-primary' : 'text-muted']">Desktop</span>
-          <span class="font-code text-[10px] text-muted">{{ token.desktop }}</span>
-        </div>
-        <div class="flex flex-col gap-0.5">
-          <span :class="['text-[9px] font-semibold uppercase tracking-wider', breakpoint === 'tablet' ? 'text-primary' : 'text-muted']">Tablet</span>
-          <span class="font-code text-[10px] text-muted">{{ token.tablet }}</span>
-        </div>
-        <div class="flex flex-col gap-0.5">
-          <span :class="['text-[9px] font-semibold uppercase tracking-wider', breakpoint === 'mobile' ? 'text-primary' : 'text-muted']">Mobile</span>
-          <span class="font-code text-[10px] text-muted">{{ token.mobile }}</span>
+      <div class="grid grid-cols-2 gap-x-3 gap-y-3 w-full m-0 mt-3">
+        <div
+          v-for="(value, bp) in token.responsive"
+          :key="bp"
+          class="flex flex-col gap-0.5"
+        >
+          <span
+            :class="[
+              'text-[9px] font-semibold uppercase tracking-wider',
+              breakpoint === bp ? 'text-primary' : 'text-muted',
+            ]"
+          >{{ BREAKPOINT_LABELS[bp] ?? bp }}</span>
+          <span class="font-code text-[10px] text-muted">{{ value }}</span>
         </div>
       </div>
     </div>
 
-    <div class="flex w-full">
+    <div class="flex w-full flex-1">
       <div class="bg-surface border border-default rounded-lg p-4 min-h-[80px] flex items-center justify-center w-full">
-        <!-- Max-width visualization -->
-        <div
-          v-if="token.property === 'max-width'"
-          class="bg-orange-500/15 border-2 border-dashed border-primary rounded h-10 w-full flex items-center justify-center"
-          :style="{ maxWidth: token[breakpoint] ?? token.desktop }"
-        >
-          <span class="font-code text-[11px] text-muted">{{ token[breakpoint] ?? token.desktop }}</span>
-        </div>
-
-        <!-- Padding visualization -->
-        <div
-          v-else-if="token.property.includes('padding')"
-          class="w-full"
-        >
+        <div class="w-full" :style="{ padding: activeValue }">
           <div
-            class="bg-orange-500/15 rounded border-2 border-dashed border-primary"
-            :style="{ padding: token[breakpoint] ?? token.desktop }"
+            class="bg-[var(--primary)]/20 rounded border-2 border-dashed border-[var(--border-selected)] bg-surface px-3 py-2 text-center"
           >
-            <div class="bg-surface rounded border border-subtle px-3 py-2 min-w-[80px] text-center">
-              <span class="font-code text-[11px] text-default">{{ token[breakpoint] ?? token.desktop }}</span>
-            </div>
+            <span class="font-code text-[11px] text-default">{{ activeValue }}</span>
           </div>
         </div>
-
-        <!-- Gap visualization -->
-        <div
-          v-else-if="token.property === 'gap'"
-          class="flex w-full"
-          :style="{ gap: token[breakpoint] ?? token.desktop }"
-        >
-          <div class="flex-1 h-8 rounded bg-orange-500/30" />
-          <div class="flex-1 h-8 rounded bg-orange-500/30" />
-          <div class="flex-1 h-8 rounded bg-orange-500/30" />
-        </div>
       </div>
     </div>
   </div>
diff --git a/apps/storybook/src/foundations/components/TypographyPreview.vue b/apps/storybook/src/foundations/components/TypographyPreview.vue
index ff5e758dd..ba96eead9 100644
--- a/apps/storybook/src/foundations/components/TypographyPreview.vue
+++ b/apps/storybook/src/foundations/components/TypographyPreview.vue
@@ -1,17 +1,25 @@
 <script setup>
-import { ref } from 'vue';
+import { ref, computed } from 'vue';
 import { useViewport } from '../composables/useViewport.js';
 
-defineProps({
-  /**
-   * Typography token object:
-   * { name, category, label, description, desktop, tablet, mobile, fontFamily, sample }
-   */
+const BREAKPOINT_ORDER = ['_', 'sm', 'md', 'lg', 'xl', '2xl'];
+
+const props = defineProps({
+  /** Token from texts.data.js (via from-tokens.js) */
   token: { type: Object, required: true },
 });
 
 const { breakpoint } = useViewport();
 
+const BREAKPOINT_LABELS = {
+  _: 'Base',
+  sm: 'sm ≥640',
+  md: 'md ≥768',
+  lg: 'lg ≥1024',
+  xl: 'xl ≥1280',
+  '2xl': '2xl ≥1536',
+};
+
 const copiedKey = ref(null);
 let copyTimeout = null;
 
@@ -27,64 +35,65 @@ function copyToClipboard(text, key) {
 function isCopied(key) {
   return copiedKey.value === key;
 }
+
+const activeValues = computed(() => {
+  const index = BREAKPOINT_ORDER.indexOf(breakpoint.value);
+  for (let i = index; i >= 0; i -= 1) {
+    const bp = BREAKPOINT_ORDER[i];
+    if (props.token.responsive[bp]?.fontSize) return props.token.responsive[bp];
+  }
+  return props.token.responsive._ ?? { fontSize: '', lineHeight: '' };
+});
 </script>
 
 <template>
   <div class="flex flex-col gap-4 py-5 border-b border-subtle items-start last:border-b-0 sm:flex-row sm:gap-6">
-    <div class="w-full flex flex-col gap-1.5 sm:w-72 sm:flex-none">
+    <div class="w-full flex flex-col gap-1.5 sm:w-80 sm:flex-none">
       <p class="text-sm font-semibold text-default m-0">{{ token.label }}</p>
       <button
         class="inline-flex items-center gap-1.5 bg-none border-none p-0 cursor-pointer font-inherit group"
-        @click="copyToClipboard(token.name, token.name)"
-        :title="'Copy: ' + token.name"
+        @click="copyToClipboard(token.usageClass, token.name)"
+        :title="'Copy class: ' + token.usageClass"
       >
-        <code class="font-code text-[11px] bg-white/[0.07] border border-white/15 text-code px-1.5 py-0.5 rounded w-fit">{{ token.name }}</code>
-        <i :class="[
-          'pi text-[10px] transition-opacity duration-100',
-          isCopied(token.name) ? 'pi-check text-success' : 'pi-copy opacity-0 group-hover:opacity-50'
-        ]" />
+        <code class="font-code text-[11px] bg-white/[0.07] border border-white/15 text-code px-1.5 py-0.5 rounded w-fit">{{ token.usageClass }}</code>
+        <i
+          :class="[
+            'pi text-[10px] transition-opacity duration-100',
+            isCopied(token.name) ? 'pi-check text-success' : 'pi-copy opacity-0 group-hover:opacity-50',
+          ]"
+        />
       </button>
       <p class="text-xs text-muted m-0 mb-2 leading-relaxed">{{ token.description }}</p>
+      <p class="text-[10px] text-muted m-0 font-code">Source: packages/theme/src/tokens/semantic/texts.data.js</p>
 
-      <div class="grid grid-cols-2 gap-x-3 gap-y-3 m-0">
+      <div class="grid grid-cols-2 gap-x-3 gap-y-3 m-0 mt-3">
         <div class="flex flex-col gap-0.5">
           <span class="text-[9px] font-semibold uppercase tracking-wider text-muted">Font</span>
           <span class="font-code text-[10px] text-muted">{{ token.fontFamily }}</span>
         </div>
-        <div class="flex flex-col gap-0.5">
-          <span :class="['text-[9px] font-semibold uppercase tracking-wider', breakpoint === 'desktop' ? 'text-primary' : 'text-muted']">Desktop</span>
-          <span class="font-code text-[10px] text-muted">{{ token.desktop.fontSize }} / {{ token.desktop.lineHeight }}</span>
-        </div>
-        <div class="flex flex-col gap-0.5">
-          <span :class="['text-[9px] font-semibold uppercase tracking-wider', breakpoint === 'tablet' ? 'text-primary' : 'text-muted']">Tablet</span>
-          <span class="font-code text-[10px] text-muted">{{ token.tablet.fontSize }} / {{ token.tablet.lineHeight }}</span>
-        </div>
-        <div class="flex flex-col gap-0.5">
-          <span :class="['text-[9px] font-semibold uppercase tracking-wider', breakpoint === 'mobile' ? 'text-primary' : 'text-muted']">Mobile</span>
-          <span class="font-code text-[10px] text-muted">{{ token.mobile.fontSize }} / {{ token.mobile.lineHeight }}</span>
-        </div>
-        <div v-if="token.desktop.letterSpacing" class="flex flex-col gap-0.5">
-          <span class="text-[9px] font-semibold uppercase tracking-wider text-muted">Tracking</span>
-          <span class="font-code text-[10px] text-muted">{{ token[breakpoint]?.letterSpacing ?? token.desktop.letterSpacing }}</span>
-        </div>
-        <div v-if="token.desktop.textTransform" class="flex flex-col gap-0.5">
-          <span class="text-[9px] font-semibold uppercase tracking-wider text-muted">Transform</span>
-          <span class="font-code text-[10px] text-muted">{{ token[breakpoint]?.textTransform ?? token.desktop.textTransform }}</span>
+        <div
+          v-for="(values, bp) in token.responsive"
+          :key="bp"
+          class="flex flex-col gap-0.5"
+        >
+          <span
+            :class="[
+              'text-[9px] font-semibold uppercase tracking-wider',
+              breakpoint === bp ? 'text-primary' : 'text-muted',
+            ]"
+          >{{ BREAKPOINT_LABELS[bp] ?? bp }}</span>
+          <span class="font-code text-[10px] text-muted">{{ values.fontSize }} / {{ values.lineHeight }}</span>
         </div>
       </div>
     </div>
 
-    <div class="flex-1 min-w-0">
+    <div class="flex-1 min-w-0 w-full">
       <div class="bg-surface border border-default rounded-lg p-6 flex items-center justify-center min-h-[80px]">
-        <span
-          :class="token.name"
-          class="text-default"
-          :style="{
-            fontSize: token[breakpoint]?.fontSize ?? token.desktop.fontSize,
-            lineHeight: token[breakpoint]?.lineHeight ?? token.desktop.lineHeight,
-          }"
-        >{{ token.sample }}</span>
+        <span :class="[token.usageClass, 'text-default']">{{ token.sample }}</span>
       </div>
+      <p class="text-[10px] text-muted m-0 mt-2 font-code">
+        Active ({{ BREAKPOINT_LABELS[breakpoint] ?? breakpoint }}): {{ activeValues.fontSize }} / {{ activeValues.lineHeight }}
+      </p>
     </div>
   </div>
 </template>
diff --git a/apps/storybook/src/foundations/components/layout/ArchitectureDiagram.vue b/apps/storybook/src/foundations/components/layout/ArchitectureDiagram.vue
index 906ecab9f..cb4212759 100644
--- a/apps/storybook/src/foundations/components/layout/ArchitectureDiagram.vue
+++ b/apps/storybook/src/foundations/components/layout/ArchitectureDiagram.vue
@@ -1,7 +1,6 @@
 <script setup>
 /**
- * ArchitectureDiagram - Visual representation of token architecture
- * Shows the flow from primitives to semantic to specific tokens
+ * Token architecture — primitives → theme → responsive semantic (DESIGN.md)
  */
 defineProps({
   layers: {
@@ -9,39 +8,39 @@ defineProps({
     default: () => [
       {
         number: 'Layer 1',
-        title: 'Primitive Colors',
-        description: 'Raw palette values. 9 color families × 11 shades each.',
-        code: 'primitives.brand.500'
+        title: 'Primitives',
+        description: 'Raw palettes, shape, typography, and effects. Theme-invariant.',
+        code: 'primitives/colors/colors.js',
       },
       {
         number: 'Layer 2',
-        title: 'Semantic Tokens',
-        description: 'Intent-based roles with theme switch resolution.',
-        code: 'text-primary'
+        title: 'Theme',
+        description: 'Light/dark semantic roles: primary, surfaces, text, borders, feedback.',
+        code: 'tokens/theme/primary.js',
       },
       {
         number: 'Layer 3',
-        title: 'Specific Tokens',
-        description: 'Class names for specific components.',
-        code: 'text-button-primary'
-      }
-    ]
-  }
-})
+        title: 'Responsive semantic',
+        description: 'Mobile-first bundles: texts.data.js, spacings.data.js.',
+        code: 'text-heading-md · var(--spacing-md)',
+      },
+    ],
+  },
+});
 </script>
 
 <template>
-  <div class="grid grid-cols-[1fr_auto_1fr_auto_1fr] gap-0 items-center mb-12">
+  <div class="grid grid-cols-1 md:grid-cols-[1fr_auto_1fr_auto_1fr] gap-4 md:gap-0 items-center mb-12">
     <template v-for="(layer, index) in layers" :key="index">
       <div class="bg-surface/5 border border-default rounded-[10px] px-5 py-5">
         <p class="text-overline-xs text-muted m-0 mb-1.5">{{ layer.number }}</p>
         <p class="text-body-sm text-default font-semibold m-0 mb-1.5">{{ layer.title }}</p>
         <p class="text-body-xs text-muted m-0 mb-3 leading-relaxed">{{ layer.description }}</p>
-        <code class="font-code text-[11px] text-muted bg-white/[0.04] px-1.5 py-0.5 rounded">{{ layer.code }}</code>
+        <code class="font-code text-[11px] text-muted bg-white/[0.04] px-1.5 py-0.5 rounded block break-all">{{ layer.code }}</code>
       </div>
       <div
         v-if="index < layers.length - 1"
-        class="px-3.5 text-muted text-xl select-none"
+        class="hidden md:block px-3.5 text-muted text-xl select-none text-center"
       >
         →
       </div>
diff --git a/apps/storybook/src/foundations/composables/useViewport.js b/apps/storybook/src/foundations/composables/useViewport.js
index 1c751cb9a..2b24c178f 100644
--- a/apps/storybook/src/foundations/composables/useViewport.js
+++ b/apps/storybook/src/foundations/composables/useViewport.js
@@ -1,21 +1,14 @@
 import { ref, onMounted, onUnmounted } from 'vue';
+import { getActiveBreakpoint } from '../utils/from-tokens.js';
 
-const BREAKPOINTS = {
-  mobile: 640,
-  tablet: 1024,
-};
-
-function getBreakpoint(width) {
-  if (width < BREAKPOINTS.mobile) return 'mobile';
-  if (width < BREAKPOINTS.tablet) return 'tablet';
-  return 'desktop';
-}
+/** @typedef {'_' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'} BreakpointKey */
 
 export function useViewport() {
-  const breakpoint = ref('desktop');
+  /** @type {import('vue').Ref<BreakpointKey>} */
+  const breakpoint = ref('_');
 
   function update() {
-    breakpoint.value = getBreakpoint(window.innerWidth);
+    breakpoint.value = getActiveBreakpoint(window.innerWidth);
   }
 
   onMounted(() => {
diff --git a/apps/storybook/src/foundations/data/spacing.js b/apps/storybook/src/foundations/data/spacing.js
index d2608964a..7825c0e80 100644
--- a/apps/storybook/src/foundations/data/spacing.js
+++ b/apps/storybook/src/foundations/data/spacing.js
@@ -1,144 +1,12 @@
 /**
- * Foundations / Spacing — data layer
- *
- * Static JS array mirroring the CSS values from semantic-spacing-plugin.
- * Class name strings appear as literals so Tailwind's scanner includes them.
+ * Spacing catalog — sourced from packages/theme/src/tokens/semantic/spacings.data.js
  */
-
-// Tailwind spacing scale: 1 unit = 0.25rem = 4px
-const toPx = (tailwindUnits) => `${tailwindUnits * 4}px`;
-
-// ─── Spacing Tokens ───────────────────────────────────────────────────────────
-
-export const spacingTokens = [
-  // ─── Container ─────────────────────────────────────────────────────────────
-  {
-    name: 'max-container-width',
-    category: 'container',
-    label: 'Max Container Width',
-    property: 'max-width',
-    description: 'Maximum width for page content containers',
-    desktop: '1280px',
-    tablet: '1024px',
-    mobile: '640px',
-  },
-  {
-    name: 'px-container',
-    category: 'container',
-    label: 'Container Padding X',
-    property: 'padding-left / padding-right',
-    description: 'Horizontal padding for page containers',
-    desktop: toPx(0),   // 0px
-    tablet: toPx(10),  // 40px
-    mobile: toPx(4),   // 16px
-  },
-  {
-    name: 'py-container',
-    category: 'container',
-    label: 'Container Padding Y',
-    property: 'padding-top / padding-bottom',
-    description: 'Vertical padding for page containers',
-    desktop: toPx(48), // 192px
-    tablet: toPx(32),  // 128px
-    mobile: toPx(16),  // 64px
-  },
-
-  // ─── Padding Elements ──────────────────────────────────────────────────────
-  {
-    name: 'p-elements-confortable',
-    category: 'padding',
-    label: 'Padding Comfortable',
-    property: 'padding',
-    description: 'Spacious padding for cards and panels',
-    desktop: toPx(24), // 96px
-    tablet: toPx(16),  // 64px
-    mobile: toPx(8),   // 32px
-  },
-  {
-    name: 'p-elements-base',
-    category: 'padding',
-    label: 'Padding Base',
-    property: 'padding',
-    description: 'Default padding for UI elements',
-    desktop: toPx(12), // 48px
-    tablet: toPx(8),   // 32px
-    mobile: toPx(6),   // 24px
-  },
-  {
-    name: 'p-elements-compact',
-    category: 'padding',
-    label: 'Padding Compact',
-    property: 'padding',
-    description: 'Tight padding for dense layouts',
-    desktop: toPx(6),  // 24px
-    tablet: toPx(5),   // 20px
-    mobile: toPx(4),   // 16px
-  },
-
-  // ─── Gap Elements ──────────────────────────────────────────────────────────
-  {
-    name: 'gap-elements-confortable',
-    category: 'gap',
-    label: 'Gap Comfortable',
-    property: 'gap',
-    description: 'Spacious gap between child elements',
-    desktop: toPx(24), // 96px
-    tablet: toPx(16),  // 64px
-    mobile: toPx(8),   // 32px
-  },
-  {
-    name: 'gap-elements-base',
-    category: 'gap',
-    label: 'Gap Base',
-    property: 'gap',
-    description: 'Default gap between child elements',
-    desktop: toPx(12), // 48px
-    tablet: toPx(8),   // 32px
-    mobile: toPx(6),   // 24px
-  },
-  {
-    name: 'gap-elements-compact',
-    category: 'gap',
-    label: 'Gap Compact',
-    property: 'gap',
-    description: 'Tight gap for dense layouts',
-    desktop: toPx(6),  // 24px
-    tablet: toPx(6),   // 24px
-    mobile: toPx(4),   // 16px
-  },
-
-  // ─── Gap Sections ──────────────────────────────────────────────────────────
-  {
-    name: 'gap-sections',
-    category: 'gap',
-    label: 'Gap Sections',
-    property: 'gap',
-    description: 'Large gap between major page sections',
-    desktop: toPx(48), // 192px
-    tablet: toPx(40),  // 160px
-    mobile: toPx(20),  // 80px
-  },
-];
-
-// ─── Grouped for rendering ───────────────────────────────────────────────────
-
-export const spacingGroups = [
-  {
-    category: 'container',
-    label: 'Container',
-    description: 'Page-level container constraints and padding.',
-    tokens: spacingTokens.filter((t) => t.category === 'container'),
-  },
-  {
-    category: 'padding',
-    label: 'Element Padding',
-    description: 'Internal padding for cards, panels, and UI elements.',
-    tokens: spacingTokens.filter((t) => t.category === 'padding'),
-  },
-  {
-    category: 'gap',
-    label: 'Gap',
-    description: 'Spacing between child elements in flex/grid containers.',
-    tokens: spacingTokens.filter((t) => t.category === 'gap'),
-  },
-];
+export {
+  spacingTokens,
+  spacingGroups,
+  buildSpacingTokens,
+  getActiveBreakpoint,
+  resolveResponsiveValue,
+  breakpoints,
+  breakpointRows,
+} from '../utils/from-tokens.js';
diff --git a/apps/storybook/src/foundations/data/typography.js b/apps/storybook/src/foundations/data/typography.js
index 2a9edd7f6..d03e378a1 100644
--- a/apps/storybook/src/foundations/data/typography.js
+++ b/apps/storybook/src/foundations/data/typography.js
@@ -1,247 +1,12 @@
 /**
- * Foundations / Typography — data layer
- *
- * Static JS array mirroring the CSS values from semantic-texts-plugin.
- * Class name strings appear as literals so Tailwind's scanner includes them.
+ * Typography catalog — sourced from packages/theme/src/tokens/semantic/texts.data.js
  */
-
-// ─── Typography Tokens ────────────────────────────────────────────────────────
-
-export const typographyTokens = [
-  // ─── Headings ──────────────────────────────────────────────────────────────
-  {
-    name: 'text-heading-2xl',
-    category: 'heading',
-    label: 'Heading 2XL',
-    description: 'Hero headlines, major section titles',
-    desktop: { fontSize: '3.75rem', lineHeight: '1.2' },
-    tablet: { fontSize: '3rem', lineHeight: '1.2' },
-    mobile: { fontSize: '1.875rem', lineHeight: '1.2' },
-    fontFamily: 'Sora',
-    sample: 'Hero Headline'
-  },
-  {
-    name: 'text-heading-xl',
-    category: 'heading',
-    label: 'Heading XL',
-    description: 'Page titles, primary headings',
-    desktop: { fontSize: '2.25rem', lineHeight: '1.2' },
-    tablet: { fontSize: '1.875rem', lineHeight: '1.2' },
-    mobile: { fontSize: '1.25rem', lineHeight: '1.2' },
-    fontFamily: 'Sora',
-    sample: 'Page Title'
-  },
-  {
-    name: 'text-heading-lg',
-    category: 'heading',
-    label: 'Heading LG',
-    description: 'Section headings, card titles',
-    desktop: { fontSize: '1.875rem', lineHeight: '1.2' },
-    tablet: { fontSize: '1.125rem', lineHeight: '1.2' },
-    mobile: { fontSize: '1.125rem', lineHeight: '1.2' },
-    fontFamily: 'Sora',
-    sample: 'Section Heading'
-  },
-  {
-    name: 'text-heading-md',
-    category: 'heading',
-    label: 'Heading MD',
-    description: 'Subsection headings, modal titles',
-    desktop: { fontSize: '1.5rem', lineHeight: '1.2' },
-    tablet: { fontSize: '1.25rem', lineHeight: '1.2' },
-    mobile: { fontSize: '1rem', lineHeight: '1.2' },
-    fontFamily: 'Sora',
-    sample: 'Subsection Title'
-  },
-  {
-    name: 'text-heading-sm',
-    category: 'heading',
-    label: 'Heading SM',
-    description: 'Small headings, widget titles',
-    desktop: { fontSize: '1.125rem', lineHeight: '1.2' },
-    tablet: { fontSize: '1rem', lineHeight: '1.2' },
-    mobile: { fontSize: '0.875rem', lineHeight: '1.2' },
-    fontFamily: 'Sora',
-    sample: 'Widget Title'
-  },
-
-  // ─── Body ──────────────────────────────────────────────────────────────────
-  {
-    name: 'text-body-lg',
-    category: 'body',
-    label: 'Body LG',
-    description: 'Lead paragraphs, prominent text',
-    desktop: { fontSize: '18px', lineHeight: '1.5' },
-    tablet: { fontSize: '16px', lineHeight: '1.5' },
-    mobile: { fontSize: '16px', lineHeight: '1.5' },
-    fontFamily: 'Sora',
-    sample: 'Lead paragraph text for introductions and key content.'
-  },
-  {
-    name: 'text-body-md',
-    category: 'body',
-    label: 'Body MD',
-    description: 'Default body text, paragraphs',
-    desktop: { fontSize: '16px', lineHeight: '1.5' },
-    tablet: { fontSize: '16px', lineHeight: '1.5' },
-    mobile: { fontSize: '16px', lineHeight: '1.5' },
-    fontFamily: 'Sora',
-    sample: 'Default body text for general content and descriptions.'
-  },
-  {
-    name: 'text-body-sm',
-    category: 'body',
-    label: 'Body SM',
-    description: 'Secondary text, captions, metadata',
-    desktop: { fontSize: '14px', lineHeight: '1.5' },
-    tablet: { fontSize: '14px', lineHeight: '1.5' },
-    mobile: { fontSize: '14px', lineHeight: '1.5' },
-    fontFamily: 'Sora',
-    sample: 'Secondary text for supporting information.'
-  },
-  {
-    name: 'text-body-xs',
-    category: 'body',
-    label: 'Body XS',
-    description: 'Fine print, footnotes, tiny labels',
-    desktop: { fontSize: '12px', lineHeight: '1.5' },
-    tablet: { fontSize: '12px', lineHeight: '1.5' },
-    mobile: { fontSize: '12px', lineHeight: '1.5' },
-    fontFamily: 'Sora',
-    sample: 'Fine print and footnotes.'
-  },
-  {
-    name: 'text-body-xs',
-    category: 'body',
-    label: 'Body XSS',
-    description: 'Micro text, minimal labels',
-    desktop: { fontSize: '12px', lineHeight: '1.5' },
-    tablet: { fontSize: '12px', lineHeight: '1.5' },
-    mobile: { fontSize: '12px', lineHeight: '1.5' },
-    fontFamily: 'Sora',
-    sample: 'Micro text'
-  },
-
-  // ─── Overline ──────────────────────────────────────────────────────────────
-  {
-    name: 'text-overline-md',
-    category: 'overline',
-    label: 'Overline MD',
-    description: 'Section labels, category tags',
-    desktop: {
-      fontSize: '14px',
-      lineHeight: '1.4',
-      letterSpacing: '0.08em',
-      textTransform: 'uppercase'
-    },
-    tablet: {
-      fontSize: '14px',
-      lineHeight: '1.4',
-      letterSpacing: '0.08em',
-      textTransform: 'uppercase'
-    },
-    mobile: {
-      fontSize: '14px',
-      lineHeight: '1.4',
-      letterSpacing: '0.08em',
-      textTransform: 'uppercase'
-    },
-    fontFamily: 'Sora',
-    sample: 'SECTION LABEL'
-  },
-  {
-    name: 'text-overline-sm',
-    category: 'overline',
-    label: 'Overline SM',
-    description: 'Small labels, badge text',
-    desktop: {
-      fontSize: '12px',
-      lineHeight: '1.4',
-      letterSpacing: '0.08em',
-      textTransform: 'uppercase'
-    },
-    tablet: {
-      fontSize: '12px',
-      lineHeight: '1.4',
-      letterSpacing: '0.08em',
-      textTransform: 'uppercase'
-    },
-    mobile: {
-      fontSize: '12px',
-      lineHeight: '1.4',
-      letterSpacing: '0.08em',
-      textTransform: 'uppercase'
-    },
-    fontFamily: 'Sora',
-    sample: 'SMALL LABEL'
-  },
-  {
-    name: 'text-overline-xs',
-    category: 'overline',
-    label: 'Overline XS',
-    description: 'Micro labels, tiny category tags',
-    desktop: {
-      fontSize: '10px',
-      lineHeight: '1.4',
-      letterSpacing: '0.08em',
-      textTransform: 'uppercase'
-    },
-    tablet: {
-      fontSize: '10px',
-      lineHeight: '1.4',
-      letterSpacing: '0.08em',
-      textTransform: 'uppercase'
-    },
-    mobile: {
-      fontSize: '10px',
-      lineHeight: '1.4',
-      letterSpacing: '0.08em',
-      textTransform: 'uppercase'
-    },
-    fontFamily: 'Sora',
-    sample: 'MICRO'
-  },
-
-  // ─── Special ───────────────────────────────────────────────────────────────
-  {
-    name: 'text-big-number-md',
-    category: 'special',
-    label: 'Big Number MD',
-    description: 'Large statistics, hero numbers',
-    desktop: { fontSize: '4.5rem', lineHeight: '1.2' },
-    tablet: { fontSize: '3rem', lineHeight: '1.2' },
-    mobile: { fontSize: '4.5rem', lineHeight: '1.2' },
-    fontFamily: 'Sora',
-    sample: '42'
-  }
-]
-
-// ─── Grouped for rendering ───────────────────────────────────────────────────
-
-export const typographyGroups = [
-  {
-    category: 'heading',
-    label: 'Headings',
-    description: 'Page and section titles. Use semantically (h1–h6) with matching visual weight.',
-    tokens: typographyTokens.filter((t) => t.category === 'heading')
-  },
-  {
-    category: 'body',
-    label: 'Body',
-    description: 'Paragraph and general content text. Choose size based on hierarchy and density.',
-    tokens: typographyTokens.filter((t) => t.category === 'body')
-  },
-  {
-    category: 'overline',
-    label: 'Overline',
-    description:
-      'Uppercase labels for sections and categories. High letter-spacing for legibility.',
-    tokens: typographyTokens.filter((t) => t.category === 'overline')
-  },
-  {
-    category: 'special',
-    label: 'Special',
-    description: 'Display numbers and decorative typography.',
-    tokens: typographyTokens.filter((t) => t.category === 'special')
-  }
-]
+export {
+  typographyTokens,
+  typographyGroups,
+  buildTypographyTokens,
+  getActiveBreakpoint,
+  resolveResponsiveValue,
+  breakpoints,
+  breakpointRows,
+} from '../utils/from-tokens.js';
diff --git a/apps/storybook/src/stories/foundations/GetStarted.mdx b/apps/storybook/src/stories/foundations/GetStarted.mdx
index 29308b989..8933f1af1 100644
--- a/apps/storybook/src/stories/foundations/GetStarted.mdx
+++ b/apps/storybook/src/stories/foundations/GetStarted.mdx
@@ -111,9 +111,23 @@ Use semantic tokens from `@aziontech/theme` so light/dark behavior remains consi
 5. Push branch and open PR
 ```
 
-## 6. Where To Change What
+## 6. Design Tokens (Foundations)
+
+Storybook documents the token system under **Foundations → Design Tokens**:
+
+| Page | Source in `@aziontech/theme` |
+| ---- | ----------------------------- |
+| Primitive Colors | `src/tokens/primitives/colors/` |
+| Theme Colors | `src/tokens/theme/` + `semantic/colors.js` |
+| Typography | `src/tokens/semantic/texts.data.js` |
+| Spacing | `src/tokens/semantic/spacings.data.js` |
+| Responsive | `src/tokens/primitives/breakpoints.js` |
+
+Styling rules for webkit components: `.claude/docs/DESIGN.md`.
+
+## 7. Where To Change What
 
 - **Component source**: `packages/webkit/src`
 - **Story source**: `apps/storybook/src/stories`
-- **Theme and tokens**: `packages/theme/src`
+- **Theme and tokens**: `packages/theme/src/tokens`
 - **Icons and generation pipeline**: `packages/icons`
diff --git a/apps/storybook/src/stories/foundations/Spacing.stories.js b/apps/storybook/src/stories/foundations/Spacing.stories.js
deleted file mode 100644
index 7fab050bd..000000000
--- a/apps/storybook/src/stories/foundations/Spacing.stories.js
+++ /dev/null
@@ -1,103 +0,0 @@
-import SpacingPreview from '../../foundations/components/SpacingPreview.vue';
-import { spacingGroups } from '../../foundations/data/spacing.js';
-
-import {
-  PageContainer,
-  PageHeader,
-  SectionHeader,
-  Card,
-} from '../../foundations/components/layout/index.js';
-
-// ─── Meta ─────────────────────────────────────────────────────────────────────
-
-export default {
-  title: 'Foundations/Spacing',
-  parameters: {
-    options: { showPanel: false },
-    controls: { disable: true },
-    actions: { disable: true },
-    docs: {
-      description: {
-        component: [
-          'Spacing system documentation — semantic spacing classes for Azion Design System.',
-          'All spacing classes are defined in `@aziontech/theme/tailwind/semantic-spacing-plugin`.',
-        ].join(' '),
-      },
-    },
-  },
-};
-
-// ─── Overview ─────────────────────────────────────────────────────────────────
-
-export const Overview = {
-  name: 'Overview',
-  render: () => ({
-    components: {
-      PageContainer,
-      PageHeader,
-      SectionHeader,
-      Card,
-      SpacingPreview,
-    },
-    setup() {
-      return { spacingGroups };
-    },
-    template: /* html */ `
-      <PageContainer>
-        <PageHeader title="Spacing">
-          The Azion spacing system provides <strong class="text-default">semantic spacing classes</strong>
-          for consistent layout and density. Classes adapt automatically across desktop, tablet, and mobile breakpoints.
-        </PageHeader>
-
-        <!-- Density scale -->
-        <SectionHeader title="Density Scale" />
-        <div class="flex gap-4 mb-12 flex-wrap">
-          <Card class="flex-1 min-w-[140px]">
-            <p class="text-overline-xs text-muted m-0 mb-1">Comfortable</p>
-            <p class="text-body-sm text-default m-0 mb-1 font-semibold">Spacious</p>
-            <p class="text-body-xs text-muted m-0">96px / 64px / 32px</p>
-          </Card>
-          <Card class="flex-1 min-w-[140px]">
-            <p class="text-overline-xs text-muted m-0 mb-1.5">Base</p>
-            <p class="text-body-sm text-default m-0 mb-1 font-semibold">Default</p>
-            <p class="text-body-xs text-muted m-0">48px / 32px / 24px</p>
-          </Card>
-          <Card class="flex-1 min-w-[140px]">
-            <p class="text-overline-xs text-muted m-0 mb-1">Compact</p>
-            <p class="text-body-sm text-default m-0 mb-1 font-semibold">Dense</p>
-            <p class="text-body-xs text-muted m-0">24px / 20px / 16px</p>
-          </Card>
-        </div>
-
-        <!-- Semantic Spacing Classes -->
-        <SectionHeader
-          title="Semantic Spacing Classes"
-          description="Complete spacing scale with responsive values. Each class adapts across desktop, tablet, and mobile breakpoints."
-          size="lg"
-        />
-
-        <div
-          v-for="group in spacingGroups"
-          :key="group.category"
-          class="mb-10"
-        >
-          <h3 class="text-heading-sm text-default m-0 mb-1">{{ group.label }}</h3>
-          <p class="text-body-xs text-muted m-0 mb-4">{{ group.description }}</p>
-
-          <div class="border border-default rounded-lg px-5">
-            <SpacingPreview
-              v-for="token in group.tokens"
-              :key="token.name"
-              :token="token"
-            />
-          </div>
-        </div>
-      </PageContainer>
-    `,
-  }),
-  parameters: {
-    docs: {
-      description: { story: 'Spacing system overview: density scale and complete semantic spacing classes.' },
-    },
-  },
-};
diff --git a/apps/storybook/src/stories/foundations/Typography.stories.js b/apps/storybook/src/stories/foundations/Typography.stories.js
deleted file mode 100644
index 60125bfd3..000000000
--- a/apps/storybook/src/stories/foundations/Typography.stories.js
+++ /dev/null
@@ -1,103 +0,0 @@
-import TypographyPreview from '../../foundations/components/TypographyPreview.vue';
-import { typographyGroups } from '../../foundations/data/typography.js';
-
-import {
-  PageContainer,
-  PageHeader,
-  SectionHeader,
-  Card,
-} from '../../foundations/components/layout/index.js';
-
-// ─── Meta ─────────────────────────────────────────────────────────────────────
-
-export default {
-  title: 'Foundations/Typography',
-  parameters: {
-    options: { showPanel: false },
-    controls: { disable: true },
-    actions: { disable: true },
-    docs: {
-      description: {
-        component: [
-          'Typography system documentation — semantic text styles for Azion Design System.',
-          'All typography classes are defined in `@aziontech/theme/tailwind/semantic-texts-plugin`.',
-        ].join(' '),
-      },
-    },
-  },
-};
-
-// ─── Overview ─────────────────────────────────────────────────────────────────
-
-export const Overview = {
-  name: 'Overview',
-  render: () => ({
-    components: {
-      PageContainer,
-      PageHeader,
-      SectionHeader,
-      Card,
-      TypographyPreview,
-    },
-    setup() {
-      return { typographyGroups };
-    },
-    template: /* html */ `
-      <PageContainer>
-        <PageHeader title="Typography">
-          The Azion typography system uses <strong class="text-default">Sora</strong> as the primary typeface.
-          Semantic text classes provide consistent sizing, line heights, and letter spacing across all components.
-        </PageHeader>
-
-        <!-- Font family -->
-        <SectionHeader title="Font Family" />
-        <div class="grid grid-cols-3 gap-5 mb-12">
-          <Card class="p-6">
-            <p class="text-overline-xs text-muted m-0 mb-2">Primary</p>
-            <p class="text-[28px] font-semibold text-default m-0 mb-1 font-sans">Sora</p>
-            <p class="text-body-xs text-muted m-0">All UI text, headings, and body copy.</p>
-          </Card>
-          <Card class="p-6">
-            <p class="text-overline-xs text-muted m-0 mb-2">Display Mono</p>
-            <p class="text-[28px] font-semibold text-default m-0 mb-1 font-proto">Proto Mono</p>
-            <p class="text-body-xs text-muted m-0">Overlines, actions, and special cases.</p>
-          </Card>
-          <Card class="p-6">
-            <p class="text-overline-xs text-muted m-0 mb-2">Monospace</p>
-            <p class="text-[28px] font-semibold text-default m-0 mb-1 font-code">Roboto Mono</p>
-            <p class="text-body-xs text-muted m-0">Code, tokens, and technical values.</p>
-          </Card>
-        </div>
-
-        <!-- Type Scale -->
-        <SectionHeader
-          title="Type Scale"
-          description="Complete type scale with responsive values. Each class adapts font size across desktop, tablet, and mobile breakpoints."
-          size="lg"
-        />
-
-        <div
-          v-for="group in typographyGroups"
-          :key="group.category"
-          class="mb-10"
-        >
-          <h3 class="text-heading-sm text-default m-0 mb-1">{{ group.label }}</h3>
-          <p class="text-body-xs text-muted m-0 mb-4">{{ group.description }}</p>
-
-          <div class="border border-default rounded-lg px-5">
-            <TypographyPreview
-              v-for="token in group.tokens"
-              :key="token.name"
-              :token="token"
-            />
-          </div>
-        </div>
-      </PageContainer>
-    `,
-  }),
-  parameters: {
-    docs: {
-      description: { story: 'Typography system overview: font families and complete type scale.' },
-    },
-  },
-};

From 6670c5a23d4d742893c869cf2b7ded59f7881b9c Mon Sep 17 00:00:00 2001
From: gablisboa <gablisboa1@gmail.com>
Date: Wed, 27 May 2026 10:50:26 -0300
Subject: [PATCH 2/5] docs(foundations): improve colors palette browsing and
 copy UX

Split Colors into Primitives and Brand sections with per-palette headers, and make swatches fully clickable/keyboard-accessible with token-aligned styling so token discovery and copying are faster and more consistent.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../components/ColorPaletteSection.vue        |  84 +++++++++++++
 .../components/layout/PageContainer.vue       |  18 +--
 apps/storybook/src/foundations/data/colors.js |  11 ++
 .../src/stories/foundations/Colors.stories.js | 116 ++++++++++++++++++
 4 files changed, 212 insertions(+), 17 deletions(-)
 create mode 100644 apps/storybook/src/foundations/components/ColorPaletteSection.vue
 create mode 100644 apps/storybook/src/foundations/data/colors.js
 create mode 100644 apps/storybook/src/stories/foundations/Colors.stories.js

diff --git a/apps/storybook/src/foundations/components/ColorPaletteSection.vue b/apps/storybook/src/foundations/components/ColorPaletteSection.vue
new file mode 100644
index 000000000..ad2cf85fe
--- /dev/null
+++ b/apps/storybook/src/foundations/components/ColorPaletteSection.vue
@@ -0,0 +1,84 @@
+<script setup>
+  import { ref } from 'vue'
+
+  defineProps({
+    title: { type: String, required: true },
+    items: { type: Array, default: () => [] }
+  })
+
+  const copiedKey = ref(null)
+  let copyTimeout = null
+
+  function copyToClipboard(value, key) {
+    if (!value) return
+    navigator.clipboard?.writeText(value).catch(() => {})
+    copiedKey.value = key
+    if (copyTimeout) clearTimeout(copyTimeout)
+    copyTimeout = setTimeout(() => {
+      copiedKey.value = null
+    }, 1000)
+  }
+
+  function isCopied(key) {
+    return copiedKey.value === key
+  }
+
+  function labelColor(hex) {
+    const value = (hex ?? '').replace('#', '').slice(0, 6)
+    if (value.length < 6) return '#fff'
+    const r = parseInt(value.slice(0, 2), 16)
+    const g = parseInt(value.slice(2, 4), 16)
+    const b = parseInt(value.slice(4, 6), 16)
+    return 0.299 * r + 0.587 * g + 0.114 * b > 140 ? '#000' : '#fff'
+  }
+</script>
+
+<template>
+  <section class="mb-[var(--spacing-xxl)]">
+    <div class="mb-[var(--spacing-md)]">
+      <h2
+        class="m-0 mb-[var(--spacing-xs)] border-b border-[var(--border-default)] pb-[var(--spacing-xs)] !text-overline-md text-[var(--text-muted)]"
+      >
+        {{ title }}
+      </h2>
+    </div>
+
+    <div class="flex w-full flex-row flex-wrap gap-[var(--spacing-sm)]">
+      <article
+        v-for="item in items"
+        :key="item.id"
+        class="w-full min-w-[var(--container-3xs)] flex-1 cursor-pointer overflow-hidden rounded-[var(--shape-card)] border border-[var(--border-default)] bg-[var(--bg-surface)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring-color)] focus-visible:ring-offset-1 focus-visible:ring-offset-[var(--bg-canvas)]"
+        role="button"
+        tabindex="0"
+        :title="isCopied(`${item.id}-value`) ? 'Copied!' : 'Copy variable name'"
+        @click="copyToClipboard(item.meta ?? item.value, `${item.id}-value`)"
+        @keydown.enter.prevent="copyToClipboard(item.meta ?? item.value, `${item.id}-value`)"
+        @keydown.space.prevent="copyToClipboard(item.meta ?? item.value, `${item.id}-value`)"
+      >
+        <div
+          class="flex h-24 flex-col px-[var(--spacing-sm)] py-[var(--spacing-xs)] font-code"
+          :style="{ background: item.preview ?? item.value ?? 'transparent' }"
+        >
+          <span
+            class="font-code text-body-xs font-semibold"
+            :style="{ color: labelColor(item.preview ?? item.value) }"
+          >
+            {{ item.label }}
+          </span>
+          <span
+            class="font-code text-body-xs"
+            :style="{ color: labelColor(item.preview ?? item.value) }"
+          >
+            {{ isCopied(`${item.id}-value`) ? 'Copied' : item.value }}
+          </span>
+        </div>
+
+        <div
+          class="flex items-center justify-between gap-[var(--spacing-xs)] bg-[var(--bg-mask)] px-[var(--spacing-sm)] py-[var(--spacing-xs)] font-code"
+        >
+          <span class="truncate text-body-xs text-[var(--text-muted)]">{{ item.meta }}</span>
+        </div>
+      </article>
+    </div>
+  </section>
+</template>
diff --git a/apps/storybook/src/foundations/components/layout/PageContainer.vue b/apps/storybook/src/foundations/components/layout/PageContainer.vue
index 49c492cc7..95c6c73bf 100644
--- a/apps/storybook/src/foundations/components/layout/PageContainer.vue
+++ b/apps/storybook/src/foundations/components/layout/PageContainer.vue
@@ -1,21 +1,5 @@
-<script setup>
-/**
- * PageContainer - Standard page wrapper with max-width and padding
- * Used as the root element for all foundation documentation pages
- */
-defineProps({
-  maxWidth: {
-    type: String,
-    default: '1000px'
-  }
-})
-</script>
-
 <template>
-  <div
-    class="font-sans py-10 px-10"
-    :style="{ maxWidth }"
-  >
+  <div class="font-sans w-full mx-auto max-w-[var(--container-7xl)]">
     <slot />
   </div>
 </template>
diff --git a/apps/storybook/src/foundations/data/colors.js b/apps/storybook/src/foundations/data/colors.js
new file mode 100644
index 000000000..41e265383
--- /dev/null
+++ b/apps/storybook/src/foundations/data/colors.js
@@ -0,0 +1,11 @@
+/**
+ * Color catalogs — primitives and theme layers from packages/theme/src/tokens/
+ */
+export {
+  primitiveColorFamilies,
+  themeColorGroups,
+  backgroundTokens,
+  textTokens,
+  borderTokens,
+  playgroundColorTokens,
+} from '../utils/from-tokens.js';
diff --git a/apps/storybook/src/stories/foundations/Colors.stories.js b/apps/storybook/src/stories/foundations/Colors.stories.js
new file mode 100644
index 000000000..7466023ba
--- /dev/null
+++ b/apps/storybook/src/stories/foundations/Colors.stories.js
@@ -0,0 +1,116 @@
+import { primitives } from '../../../../../packages/theme/src/tokens/primitives/colors/colors.js'
+import ColorPaletteSection from '../../foundations/components/ColorPaletteSection.vue'
+import { PageContainer, PageHeader } from '../../foundations/components/layout/index.js'
+
+const brandPaletteSections = Object.entries(primitives.brand ?? {})
+  .map(([familyName, scale]) => {
+    if (!scale || typeof scale !== 'object') return null
+
+    const items = Object.entries(scale).map(([shade, hex]) => {
+      const shadeSuffix = String(shade)
+      return {
+        id: `brand-${familyName}-${shadeSuffix}`,
+        label: `${familyName} ${shadeSuffix}`,
+        value: hex,
+        preview: hex,
+        meta: `--brand-${familyName}-${shadeSuffix}`
+      }
+    })
+
+    return {
+      id: `brand-${familyName}`,
+      title: familyName,
+      description: `Brand ${familyName} primitive scale.`,
+      items
+    }
+  })
+  .filter(Boolean)
+
+const shadeScaleKeys = [
+  'orange',
+  'violet',
+  'blue',
+  'green',
+  'yellow',
+  'red',
+  'gray',
+  'slate',
+  'surface'
+]
+
+const shadePaletteSections = shadeScaleKeys
+  .map((scaleKey) => {
+    const scale = primitives[scaleKey]
+    if (!scale || typeof scale !== 'object') return null
+
+    const items = Object.entries(scale).map(([shade, hex]) => ({
+      id: `${scaleKey}-${shade}`,
+      label: `${scaleKey} ${shade}`,
+      value: hex,
+      preview: hex,
+      meta: `--${scaleKey}-${shade}`
+    }))
+
+    return {
+      id: `primitive-${scaleKey}`,
+      title: scaleKey,
+      description: `${scaleKey} primitive scale from theme tokens.`,
+      items
+    }
+  })
+  .filter(Boolean)
+
+export default {
+  title: 'Foundations/Colors',
+  parameters: {
+    options: { showPanel: false },
+    controls: { disable: true },
+    actions: { disable: true },
+    docs: {
+      description: {
+        component:
+          'Color foundations with a Wires-like layout. Every swatch is copyable and mapped to Azion theme tokens.'
+      }
+    }
+  }
+}
+
+export const Overview = {
+  name: 'Overview',
+  render: () => ({
+    components: { PageContainer, PageHeader, ColorPaletteSection },
+    setup() {
+      return { brandPaletteSections, shadePaletteSections }
+    },
+    template: /* html */ `
+      <PageContainer>
+        <PageHeader title="Colors">
+          Shared foundations layout using the same header + palette blocks.
+          Click a swatch value to copy it. Use semantic tokens in components and keep primitive shades for reference.
+        </PageHeader>
+
+        <section class="mb-[var(--spacing-xxl)]">
+          <h2 class="m-0 mb-[var(--spacing-md)] text-heading-lg text-[var(--text-default)]">Primitives</h2>
+          <ColorPaletteSection
+            v-for="section in shadePaletteSections"
+            :key="section.id"
+            :title="section.title"
+            :description="section.description"
+            :items="section.items"
+          />
+        </section>
+
+        <section class="mb-[var(--spacing-xxl)]">
+          <h2 class="m-0 mb-[var(--spacing-md)] text-heading-lg text-[var(--text-default)]">Brand</h2>
+          <ColorPaletteSection
+            v-for="section in brandPaletteSections"
+            :key="section.id"
+            :title="section.title"
+            :description="section.description"
+            :items="section.items"
+          />
+        </section>
+      </PageContainer>
+    `
+  })
+}

From 5f0878da783460ce7d100043e341c61a7fc605a2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gabriel=20Mendon=C3=A7a?= <gabriel.mendonca@azion.com>
Date: Tue, 2 Jun 2026 11:51:17 -0300
Subject: [PATCH 3/5] docs(foundations): typography catalog from texts.data and
 text token updates

Expose typographyCatalog from theme, rebuild dist tokens, and add a
Foundations/Typography Storybook catalog aligned with the new data source.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .claude/docs/DESIGN.md                        |  13 ++
 .../components/TypographyPreview.vue          | 145 +++++++++---------
 .../stories/foundations/Typography.stories.js |  43 ++++++
 packages/theme/dist/v3/globals.css            |  10 ++
 packages/theme/dist/v3/globals.scss           |  10 ++
 packages/theme/dist/v4/globals.css            |  10 ++
 packages/theme/dist/v4/globals.scss           |  10 ++
 packages/theme/package.json                   |   1 +
 packages/theme/src/scripts/build-tokens.mjs   |  28 +++-
 packages/theme/src/tests/tokens.html          |   3 +
 packages/theme/src/tokens/README.md           |  17 ++
 packages/theme/src/tokens/index.js            |   5 +
 .../theme/src/tokens/semantic/texts.data.js   |  54 ++++++-
 13 files changed, 277 insertions(+), 72 deletions(-)
 create mode 100644 apps/storybook/src/stories/foundations/Typography.stories.js

diff --git a/.claude/docs/DESIGN.md b/.claude/docs/DESIGN.md
index d25fe3c97..9d403edc7 100644
--- a/.claude/docs/DESIGN.md
+++ b/.claude/docs/DESIGN.md
@@ -46,6 +46,7 @@ Reference: `packages/webkit/src/components/webkit/actions/button/button.vue`.
 | `text-label-sm` / `text-label-md` / `text-label-lg`                | Labels, compact UI text                  |
 | `text-overline-md` / `text-overline-sm` / `text-overline-xs`       | Overlines (uppercase, tracking baked in) |
 | `text-button-lg` / `text-button-md`                                | Button labels                            |
+| `text-link`                                                        | Inline `<a>` inside body/heading copy (inherits parent size; hover underline) |
 
 These classes are **mobile-first**: font sizes can change at `sm`, `md`, etc. Do not duplicate breakpoint logic in components.
 
@@ -69,6 +70,18 @@ Font family, line height, letter spacing, and responsive font size live in `text
 <i class="shrink-0 text-[length:inherit] leading-none" />
 ```
 
+### Inline links vs navigation `Link`
+
+For anchors **inside** body or heading copy, use the `text-link` typography class on a plain `<a>` (inherits size from the parent `text-body-*` / `text-heading-*` class):
+
+```html
+<p class="text-body-md">
+  Read the <a href="/docs" class="text-link">documentation</a>.
+</p>
+```
+
+For **standalone** navigation links (icon, ghost hover surface, fixed height), use `@aziontech/webkit/navigation/link` — not `text-link` alone.
+
 ---
 
 ## Spacing
diff --git a/apps/storybook/src/foundations/components/TypographyPreview.vue b/apps/storybook/src/foundations/components/TypographyPreview.vue
index ba96eead9..f1e18e0d3 100644
--- a/apps/storybook/src/foundations/components/TypographyPreview.vue
+++ b/apps/storybook/src/foundations/components/TypographyPreview.vue
@@ -1,98 +1,103 @@
 <script setup>
-import { ref, computed } from 'vue';
-import { useViewport } from '../composables/useViewport.js';
+import { computed, ref } from 'vue'
+import { typographyCatalog, typographyLinkDemo } from '@aziontech/theme/tokens/semantic/texts.data'
+import { useViewport } from '../composables/useViewport.js'
 
-const BREAKPOINT_ORDER = ['_', 'sm', 'md', 'lg', 'xl', '2xl'];
+const { breakpoint } = useViewport()
 
-const props = defineProps({
-  /** Token from texts.data.js (via from-tokens.js) */
-  token: { type: Object, required: true },
-});
+const viewportTitle = computed(() => {
+  if (breakpoint.value === 'tablet') return 'Tablet'
+  if (breakpoint.value === 'mobile') return 'Mobile'
+  return 'Desktop'
+})
 
-const { breakpoint } = useViewport();
-
-const BREAKPOINT_LABELS = {
-  _: 'Base',
-  sm: 'sm ≥640',
-  md: 'md ≥768',
-  lg: 'lg ≥1024',
-  xl: 'xl ≥1280',
-  '2xl': '2xl ≥1536',
-};
-
-const copiedKey = ref(null);
-let copyTimeout = null;
+const copiedKey = ref(null)
+let copyTimeout = null
 
 function copyToClipboard(text, key) {
-  navigator.clipboard?.writeText(text).catch(() => {});
-  copiedKey.value = key;
-  if (copyTimeout) clearTimeout(copyTimeout);
+  navigator.clipboard?.writeText(text).catch(() => {})
+  copiedKey.value = key
+  if (copyTimeout) clearTimeout(copyTimeout)
   copyTimeout = setTimeout(() => {
-    copiedKey.value = null;
-  }, 1000);
+    copiedKey.value = null
+  }, 1000)
 }
 
 function isCopied(key) {
-  return copiedKey.value === key;
+  return copiedKey.value === key
 }
-
-const activeValues = computed(() => {
-  const index = BREAKPOINT_ORDER.indexOf(breakpoint.value);
-  for (let i = index; i >= 0; i -= 1) {
-    const bp = BREAKPOINT_ORDER[i];
-    if (props.token.responsive[bp]?.fontSize) return props.token.responsive[bp];
-  }
-  return props.token.responsive._ ?? { fontSize: '', lineHeight: '' };
-});
 </script>
 
 <template>
-  <div class="flex flex-col gap-4 py-5 border-b border-subtle items-start last:border-b-0 sm:flex-row sm:gap-6">
-    <div class="w-full flex flex-col gap-1.5 sm:w-80 sm:flex-none">
-      <p class="text-sm font-semibold text-default m-0">{{ token.label }}</p>
+  <div
+    class="flex w-full flex-col gap-[var(--spacing-xs)] rounded-[var(--shape-elements)] bg-[var(--bg-canvas)] p-[var(--spacing-xs)]"
+  >
+    <header
+      class="flex w-full items-start rounded-[var(--shape-elements)] bg-[var(--bg-canvas)] p-[var(--spacing-lg)]"
+    >
+      <p class="text-heading-xl m-0 whitespace-nowrap text-[var(--text-default)]">
+        {{ viewportTitle }}
+      </p>
+    </header>
+
+    <div
+      v-for="item in typographyCatalog"
+      :key="item.className"
+      class="flex w-full shrink-0 flex-col gap-[var(--spacing-xs)] rounded-[var(--shape-elements)] bg-[var(--bg-surface)] p-[var(--spacing-lg)]"
+    >
       <button
-        class="inline-flex items-center gap-1.5 bg-none border-none p-0 cursor-pointer font-inherit group"
-        @click="copyToClipboard(token.usageClass, token.name)"
-        :title="'Copy class: ' + token.usageClass"
+        type="button"
+        class="group inline-flex w-fit cursor-pointer items-center gap-1.5 border-none bg-transparent p-0 font-inherit"
+        :title="`Copy: ${item.className}`"
+        @click="copyToClipboard(item.className, item.className)"
       >
-        <code class="font-code text-[11px] bg-white/[0.07] border border-white/15 text-code px-1.5 py-0.5 rounded w-fit">{{ token.usageClass }}</code>
+        <code
+          class="font-code w-fit rounded border border-white/15 bg-white/[0.07] px-1.5 py-0.5 text-[11px] text-code"
+        >
+          {{ item.className }}
+        </code>
         <i
           :class="[
             'pi text-[10px] transition-opacity duration-100',
-            isCopied(token.name) ? 'pi-check text-success' : 'pi-copy opacity-0 group-hover:opacity-50',
+            isCopied(item.className)
+              ? 'pi-check text-success'
+              : 'pi-copy opacity-0 group-hover:opacity-50'
           ]"
         />
       </button>
-      <p class="text-xs text-muted m-0 mb-2 leading-relaxed">{{ token.description }}</p>
-      <p class="text-[10px] text-muted m-0 font-code">Source: packages/theme/src/tokens/semantic/texts.data.js</p>
 
-      <div class="grid grid-cols-2 gap-x-3 gap-y-3 m-0 mt-3">
-        <div class="flex flex-col gap-0.5">
-          <span class="text-[9px] font-semibold uppercase tracking-wider text-muted">Font</span>
-          <span class="font-code text-[10px] text-muted">{{ token.fontFamily }}</span>
-        </div>
-        <div
-          v-for="(values, bp) in token.responsive"
-          :key="bp"
-          class="flex flex-col gap-0.5"
-        >
-          <span
-            :class="[
-              'text-[9px] font-semibold uppercase tracking-wider',
-              breakpoint === bp ? 'text-primary' : 'text-muted',
-            ]"
-          >{{ BREAKPOINT_LABELS[bp] ?? bp }}</span>
-          <span class="font-code text-[10px] text-muted">{{ values.fontSize }} / {{ values.lineHeight }}</span>
-        </div>
-      </div>
+      <p :class="[item.className, 'm-0 break-words text-[var(--text-default)]']">
+        {{ item.styleLabel }}
+      </p>
     </div>
 
-    <div class="flex-1 min-w-0 w-full">
-      <div class="bg-surface border border-default rounded-lg p-6 flex items-center justify-center min-h-[80px]">
-        <span :class="[token.usageClass, 'text-default']">{{ token.sample }}</span>
-      </div>
-      <p class="text-[10px] text-muted m-0 mt-2 font-code">
-        Active ({{ BREAKPOINT_LABELS[breakpoint] ?? breakpoint }}): {{ activeValues.fontSize }} / {{ activeValues.lineHeight }}
+    <div
+      class="flex w-full shrink-0 flex-col gap-[var(--spacing-xs)] rounded-[var(--shape-elements)] bg-[var(--bg-surface)] p-[var(--spacing-lg)]"
+    >
+      <button
+        type="button"
+        class="group inline-flex w-fit cursor-pointer items-center gap-1.5 border-none bg-transparent p-0 font-inherit"
+        :title="`Copy: ${typographyLinkDemo.linkClass}`"
+        @click="copyToClipboard(typographyLinkDemo.linkClass, typographyLinkDemo.linkClass)"
+      >
+        <code
+          class="font-code w-fit rounded border border-white/15 bg-white/[0.07] px-1.5 py-0.5 text-[11px] text-code"
+        >
+          {{ typographyLinkDemo.linkClass }}
+        </code>
+        <i
+          :class="[
+            'pi text-[10px] transition-opacity duration-100',
+            isCopied(typographyLinkDemo.linkClass)
+              ? 'pi-check text-success'
+              : 'pi-copy opacity-0 group-hover:opacity-50'
+          ]"
+        />
+      </button>
+
+      <p :class="[typographyLinkDemo.parentClass, 'm-0 break-words text-[var(--text-default)]']">
+        Typography/Body/md with
+        <a href="#" class="text-link" @click.prevent>{{ typographyLinkDemo.linkLabel }}</a>
       </p>
     </div>
   </div>
diff --git a/apps/storybook/src/stories/foundations/Typography.stories.js b/apps/storybook/src/stories/foundations/Typography.stories.js
new file mode 100644
index 000000000..f7d0efcec
--- /dev/null
+++ b/apps/storybook/src/stories/foundations/Typography.stories.js
@@ -0,0 +1,43 @@
+import TypographyPreview from '../../foundations/components/TypographyPreview.vue';
+
+import { PageContainer, PageHeader } from '../../foundations/components/layout/index.js';
+
+export default {
+  title: 'Foundations/Typography',
+  parameters: {
+    options: { showPanel: false },
+    controls: { disable: true },
+    actions: { disable: true },
+    docs: {
+      description: {
+        component: [
+          'Typography system — semantic text classes from `@aziontech/theme`',
+          '(`packages/theme/src/tokens/semantic/texts.data.js`).',
+        ].join(' '),
+      },
+    },
+  },
+};
+
+export const Catalog = {
+  name: 'Catalog',
+  render: () => ({
+    components: { PageContainer, PageHeader, TypographyPreview },
+    template: /* html */ `
+      <PageContainer>
+        <PageHeader title="Typography">
+          Semantic text styles generated from <code class="font-code text-code">texts.data.js</code>.
+          Each row applies the matching <code class="font-code text-code">.text-*</code> class.
+        </PageHeader>
+        <TypographyPreview />
+      </PageContainer>
+    `,
+  }),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Full type catalog: one surface row per style, plus inline text-link inside body copy.',
+      },
+    },
+  },
+};
diff --git a/packages/theme/dist/v3/globals.css b/packages/theme/dist/v3/globals.css
index b9ae7d56a..497cbb139 100644
--- a/packages/theme/dist/v3/globals.css
+++ b/packages/theme/dist/v3/globals.css
@@ -528,6 +528,10 @@
     --text-button-md-font-weight: 600;
     --text-button-md-line-height: 1;
     --text-button-md-letter-spacing: 0;
+    --text-link-font-size: inherit;
+    --text-link-line-height: inherit;
+    --text-link-color: var(--text-link);
+    --text-link-transition: color 150ms ease-out;
 
     /* ── Semantic colors ── */
     --text-default: #141414;
@@ -825,4 +829,10 @@
   .text-overline-xs { font-family: var(--text-overline-xs-font-family); font-size: var(--text-overline-xs-font-size); line-height: var(--text-overline-xs-line-height); letter-spacing: var(--text-overline-xs-letter-spacing); text-transform: var(--text-overline-xs-text-transform); }
   .text-button-lg { font-family: var(--text-button-lg-font-family); font-size: var(--text-button-lg-font-size); font-weight: var(--text-button-lg-font-weight); line-height: var(--text-button-lg-line-height); letter-spacing: var(--text-button-lg-letter-spacing); }
   .text-button-md { font-family: var(--text-button-md-font-family); font-size: var(--text-button-md-font-size); font-weight: var(--text-button-md-font-weight); line-height: var(--text-button-md-line-height); letter-spacing: var(--text-button-md-letter-spacing); }
+  .text-link { font-size: var(--text-link-font-size); line-height: var(--text-link-line-height); color: var(--text-link-color); transition: var(--text-link-transition); }
+  .text-link:hover { color: var(--text-link-hover); text-decoration: underline; }
+  .text-link:focus-visible { outline: 2px solid var(--ring-color); outline-offset: 2px; }
+  @media (prefers-reduced-motion: reduce) {
+    .text-link { transition: none; }
+  }
 }
diff --git a/packages/theme/dist/v3/globals.scss b/packages/theme/dist/v3/globals.scss
index b9ae7d56a..497cbb139 100644
--- a/packages/theme/dist/v3/globals.scss
+++ b/packages/theme/dist/v3/globals.scss
@@ -528,6 +528,10 @@
     --text-button-md-font-weight: 600;
     --text-button-md-line-height: 1;
     --text-button-md-letter-spacing: 0;
+    --text-link-font-size: inherit;
+    --text-link-line-height: inherit;
+    --text-link-color: var(--text-link);
+    --text-link-transition: color 150ms ease-out;
 
     /* ── Semantic colors ── */
     --text-default: #141414;
@@ -825,4 +829,10 @@
   .text-overline-xs { font-family: var(--text-overline-xs-font-family); font-size: var(--text-overline-xs-font-size); line-height: var(--text-overline-xs-line-height); letter-spacing: var(--text-overline-xs-letter-spacing); text-transform: var(--text-overline-xs-text-transform); }
   .text-button-lg { font-family: var(--text-button-lg-font-family); font-size: var(--text-button-lg-font-size); font-weight: var(--text-button-lg-font-weight); line-height: var(--text-button-lg-line-height); letter-spacing: var(--text-button-lg-letter-spacing); }
   .text-button-md { font-family: var(--text-button-md-font-family); font-size: var(--text-button-md-font-size); font-weight: var(--text-button-md-font-weight); line-height: var(--text-button-md-line-height); letter-spacing: var(--text-button-md-letter-spacing); }
+  .text-link { font-size: var(--text-link-font-size); line-height: var(--text-link-line-height); color: var(--text-link-color); transition: var(--text-link-transition); }
+  .text-link:hover { color: var(--text-link-hover); text-decoration: underline; }
+  .text-link:focus-visible { outline: 2px solid var(--ring-color); outline-offset: 2px; }
+  @media (prefers-reduced-motion: reduce) {
+    .text-link { transition: none; }
+  }
 }
diff --git a/packages/theme/dist/v4/globals.css b/packages/theme/dist/v4/globals.css
index 1f905b0f0..b6f2b995e 100644
--- a/packages/theme/dist/v4/globals.css
+++ b/packages/theme/dist/v4/globals.css
@@ -523,6 +523,10 @@
   --text-button-md-font-weight: 600;
   --text-button-md-line-height: 1;
   --text-button-md-letter-spacing: 0;
+  --text-link-font-size: inherit;
+  --text-link-line-height: inherit;
+  --text-link-color: var(--text-link);
+  --text-link-transition: color 150ms ease-out;
 
   @media (min-width: 640px) {
     --container-px: 2.5rem;
@@ -605,4 +609,10 @@
   .text-overline-xs { font-family: var(--text-overline-xs-font-family); font-size: var(--text-overline-xs-font-size); line-height: var(--text-overline-xs-line-height); letter-spacing: var(--text-overline-xs-letter-spacing); text-transform: var(--text-overline-xs-text-transform); }
   .text-button-lg { font-family: var(--text-button-lg-font-family); font-size: var(--text-button-lg-font-size); font-weight: var(--text-button-lg-font-weight); line-height: var(--text-button-lg-line-height); letter-spacing: var(--text-button-lg-letter-spacing); }
   .text-button-md { font-family: var(--text-button-md-font-family); font-size: var(--text-button-md-font-size); font-weight: var(--text-button-md-font-weight); line-height: var(--text-button-md-line-height); letter-spacing: var(--text-button-md-letter-spacing); }
+  .text-link { font-size: var(--text-link-font-size); line-height: var(--text-link-line-height); color: var(--text-link-color); transition: var(--text-link-transition); }
+  .text-link:hover { color: var(--text-link-hover); text-decoration: underline; }
+  .text-link:focus-visible { outline: 2px solid var(--ring-color); outline-offset: 2px; }
+  @media (prefers-reduced-motion: reduce) {
+    .text-link { transition: none; }
+  }
 }
diff --git a/packages/theme/dist/v4/globals.scss b/packages/theme/dist/v4/globals.scss
index 1f905b0f0..b6f2b995e 100644
--- a/packages/theme/dist/v4/globals.scss
+++ b/packages/theme/dist/v4/globals.scss
@@ -523,6 +523,10 @@
   --text-button-md-font-weight: 600;
   --text-button-md-line-height: 1;
   --text-button-md-letter-spacing: 0;
+  --text-link-font-size: inherit;
+  --text-link-line-height: inherit;
+  --text-link-color: var(--text-link);
+  --text-link-transition: color 150ms ease-out;
 
   @media (min-width: 640px) {
     --container-px: 2.5rem;
@@ -605,4 +609,10 @@
   .text-overline-xs { font-family: var(--text-overline-xs-font-family); font-size: var(--text-overline-xs-font-size); line-height: var(--text-overline-xs-line-height); letter-spacing: var(--text-overline-xs-letter-spacing); text-transform: var(--text-overline-xs-text-transform); }
   .text-button-lg { font-family: var(--text-button-lg-font-family); font-size: var(--text-button-lg-font-size); font-weight: var(--text-button-lg-font-weight); line-height: var(--text-button-lg-line-height); letter-spacing: var(--text-button-lg-letter-spacing); }
   .text-button-md { font-family: var(--text-button-md-font-family); font-size: var(--text-button-md-font-size); font-weight: var(--text-button-md-font-weight); line-height: var(--text-button-md-line-height); letter-spacing: var(--text-button-md-letter-spacing); }
+  .text-link { font-size: var(--text-link-font-size); line-height: var(--text-link-line-height); color: var(--text-link-color); transition: var(--text-link-transition); }
+  .text-link:hover { color: var(--text-link-hover); text-decoration: underline; }
+  .text-link:focus-visible { outline: 2px solid var(--ring-color); outline-offset: 2px; }
+  @media (prefers-reduced-motion: reduce) {
+    .text-link { transition: none; }
+  }
 }
diff --git a/packages/theme/package.json b/packages/theme/package.json
index 8e7667615..3d1d61987 100644
--- a/packages/theme/package.json
+++ b/packages/theme/package.json
@@ -59,6 +59,7 @@
     "./tailwind-preset/v3": "./dist/v3/tailwind-preset.js",
     "./tailwind/semantic-spacings-plugin": "./src/tokens/semantic/spacings.js",
     "./tailwind/semantic-texts-plugin": "./src/tokens/semantic/texts.js",
+    "./tokens/semantic/texts.data": "./src/tokens/semantic/texts.data.js",
     "./tailwind/semantic-animations-plugin": "./src/tokens/semantic/animations.js",
     "./globals.css": "./dist/v3/globals.css",
     "./globals.scss": "./dist/v3/globals.scss",
diff --git a/packages/theme/src/scripts/build-tokens.mjs b/packages/theme/src/scripts/build-tokens.mjs
index cef45ad8d..66e3f27db 100644
--- a/packages/theme/src/scripts/build-tokens.mjs
+++ b/packages/theme/src/scripts/build-tokens.mjs
@@ -70,6 +70,7 @@ const flattenBundle = (data) => {
   const byBp = {};
   for (const [key, bundle] of Object.entries(data)) {
     for (const [prop, val] of Object.entries(bundle)) {
+      if (prop === 'states') continue;
       const varName = `--${key}-${kebab(prop)}`;
       for (const [bp, v] of Object.entries(splitResponsive(val))) {
         (byBp[bp] ||= {})[varName] = v;
@@ -79,6 +80,16 @@ const flattenBundle = (data) => {
   return byBp;
 };
 
+const pseudoClassName = (key) => {
+  if (key === 'focusVisible') return 'focus-visible';
+  return key;
+};
+
+const formatStateDecls = (rules) =>
+  Object.entries(rules)
+    .map(([prop, val]) => `${kebab(prop)}: ${val}`)
+    .join('; ');
+
 const SEMANTIC_PREFIXES = ['--text-', '--background-', '--border-'];
 const isSemanticVar = (key) => SEMANTIC_PREFIXES.some((p) => key.startsWith(p));
 const pickSemantic = (vars) =>
@@ -122,10 +133,24 @@ const emitComponentClasses = (indent = '  ') => {
   lines.push('');
   lines.push(`${indent}/* ── Texts ── */`);
   for (const [key, bundle] of Object.entries(textsData)) {
-    const decls = Object.keys(bundle)
+    const baseProps = Object.keys(bundle).filter((prop) => prop !== 'states');
+    const decls = baseProps
       .map((prop) => `${kebab(prop)}: var(--${key}-${kebab(prop)});`)
       .join(' ');
     lines.push(`${indent}.${key} { ${decls} }`);
+
+    if (bundle.states) {
+      for (const [pseudo, rules] of Object.entries(bundle.states)) {
+        const pseudoSuffix = pseudoClassName(pseudo);
+        lines.push(`${indent}.${key}:${pseudoSuffix} { ${formatStateDecls(rules)}; }`);
+      }
+    }
+
+    if (bundle.transition) {
+      lines.push(`${indent}@media (prefers-reduced-motion: reduce) {`);
+      lines.push(`${indent}  .${key} { transition: none; }`);
+      lines.push(`${indent}}`);
+    }
   }
 
   return lines.join('\n');
@@ -227,6 +252,7 @@ const buildPresetData = () => {
   const fontSize = {};
   for (const [key, bundle] of Object.entries(textsData)) {
     if (!('fontSize' in bundle)) continue;
+    if (bundle.fontSize === 'inherit') continue;
     const meta = {};
     if ('lineHeight' in bundle) meta.lineHeight = `var(--${key}-line-height)`;
     if ('letterSpacing' in bundle) meta.letterSpacing = `var(--${key}-letter-spacing)`;
diff --git a/packages/theme/src/tests/tokens.html b/packages/theme/src/tests/tokens.html
index 5d2395f2a..0524faf18 100644
--- a/packages/theme/src/tests/tokens.html
+++ b/packages/theme/src/tests/tokens.html
@@ -37,6 +37,9 @@ <h2>Typography (responsive)</h2>
       <p class="text-heading-sm">heading-sm — responsive</p>
       <p class="text-body-lg">body-lg — sm only at md</p>
       <p class="text-body-md">body-md — static</p>
+      <p class="text-body-md">
+        body-md with <a href="#" class="text-link">inline text-link</a>
+      </p>
       <p class="text-overline-md">overline-md — sm only at sm</p>
     </section>
 
diff --git a/packages/theme/src/tokens/README.md b/packages/theme/src/tokens/README.md
index 586362c5c..982864b34 100644
--- a/packages/theme/src/tokens/README.md
+++ b/packages/theme/src/tokens/README.md
@@ -310,6 +310,23 @@ Only useful if you can't precompile and import `globals.css` — production usag
 
 2. Rebuild. `build-tokens.mjs` emits the base var in `:root`, per-breakpoint `@media` overrides, **and** a matching `.gap-2xl { gap: var(--gap-2xl) }` utility.
 
+For typography bundles that need hover/focus without Tailwind utilities, add an optional `states` object (not flattened to CSS vars). Example — inline prose links in `texts.data.js`:
+
+```js
+'text-link': {
+  fontSize: 'inherit',
+  lineHeight: 'inherit',
+  color: 'var(--text-link)',
+  transition: 'color 150ms ease-out',
+  states: {
+    hover: { color: 'var(--text-link-hover)', textDecoration: 'underline' },
+    'focus-visible': { outline: '2px solid var(--ring-color)', outlineOffset: '2px' },
+  },
+},
+```
+
+Bundles with `fontSize: 'inherit'` are omitted from the Tailwind `fontSize` preset (avoids clashing with `textColor.link` → class `text-link`). Interaction styles are emitted under `@layer components` as `.text-link:hover`, etc.
+
 ---
 
 ## 🔗 Token references (`tokenRef`)
diff --git a/packages/theme/src/tokens/index.js b/packages/theme/src/tokens/index.js
index 523731eaa..09fcc4725 100644
--- a/packages/theme/src/tokens/index.js
+++ b/packages/theme/src/tokens/index.js
@@ -5,4 +5,9 @@
 export { createCssVars, cssVarsString, injectCssVars } from '../scripts/css-vars.js';
 export * from './primitives/colors/colors.js';
 export * from './semantic/colors.js';
+export {
+  textsData,
+  typographyCatalog,
+  typographyLinkDemo
+} from './semantic/texts.data.js';
 export * from './theme.js';
diff --git a/packages/theme/src/tokens/semantic/texts.data.js b/packages/theme/src/tokens/semantic/texts.data.js
index 591781b75..f9b46659b 100644
--- a/packages/theme/src/tokens/semantic/texts.data.js
+++ b/packages/theme/src/tokens/semantic/texts.data.js
@@ -6,6 +6,9 @@
  * from the legacy `texts.js` plugin — direction inverted from desktop-first
  * (max-width) to mobile-first (min-width).
  *
+ * Optional `states` emits pseudo-class rules (e.g. `.text-link:hover`). Bundles
+ * with `fontSize: 'inherit'` are omitted from the Tailwind `fontSize` preset.
+ *
  * Mapping used during the port:
  *   old `large`  (≤640) → `_`
  *   old `medium` (≤768) → `sm` (≥640)
@@ -119,7 +122,56 @@ export const textsData = {
     fontWeight: '600',
     lineHeight: '1',
     letterSpacing: '0'
+  },
+  /** Inline `<a>` in body/heading — inherits parent size; not the navigation Link component. */
+  'text-link': {
+    fontSize: 'inherit',
+    lineHeight: 'inherit',
+    color: 'var(--text-link)',
+    transition: 'all 150ms ease-out',
+    states: {
+      hover: {
+        color: 'var(--text-link-hover)',
+        textDecoration: 'underline'
+      },
+      'focus-visible': {
+        outline: '2px solid var(--ring-color)',
+        outlineOffset: '2px'
+      }
+    }
   }
 }
 
-export default { textsData }
+/** Display order for type catalog UIs (Storybook, docs). */
+export const typographyCatalog = [
+  { styleLabel: 'Typography/Big Number/lg', className: 'text-big-number-lg' },
+  { styleLabel: 'Typography/Big Number/md', className: 'text-big-number-md' },
+  { styleLabel: 'Typography/Big Number/sm', className: 'text-big-number-sm' },
+  { styleLabel: 'Typography/Heading/2xl', className: 'text-heading-2xl' },
+  { styleLabel: 'Typography/Heading/xl', className: 'text-heading-xl' },
+  { styleLabel: 'Typography/Heading/lg', className: 'text-heading-lg' },
+  { styleLabel: 'Typography/Heading/md', className: 'text-heading-md' },
+  { styleLabel: 'Typography/Heading/sm', className: 'text-heading-sm' },
+  { styleLabel: 'Typography/Body/lg', className: 'text-body-lg' },
+  { styleLabel: 'Typography/Body/md', className: 'text-body-md' },
+  { styleLabel: 'Typography/Body/sm', className: 'text-body-sm' },
+  { styleLabel: 'Typography/Body/xs', className: 'text-body-xs' },
+  { styleLabel: 'Typography/Body/xxs', className: 'text-body-xxs' },
+  { styleLabel: 'Typography/Label/lg', className: 'text-label-lg' },
+  { styleLabel: 'Typography/Label/md', className: 'text-label-md' },
+  { styleLabel: 'Typography/Label/sm', className: 'text-label-sm' },
+  { styleLabel: 'Typography/Overline/md', className: 'text-overline-md' },
+  { styleLabel: 'Typography/Overline/sm', className: 'text-overline-sm' },
+  { styleLabel: 'Typography/Overline/xs', className: 'text-overline-xs' },
+  { styleLabel: 'Typography/Button/lg', className: 'text-button-lg' },
+  { styleLabel: 'Typography/Button/md', className: 'text-button-md' }
+]
+
+/** Inline link demo row (parent body + `text-link` anchor). */
+export const typographyLinkDemo = {
+  parentClass: 'text-body-md',
+  linkLabel: 'Typography/Link',
+  linkClass: 'text-link'
+}
+
+export default { textsData, typographyCatalog, typographyLinkDemo }

From 559eca022cc899c822b4ff47f802819b24c43089 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gabriel=20Mendon=C3=A7a?= <gabriel.mendonca@azion.com>
Date: Tue, 2 Jun 2026 12:28:21 -0300
Subject: [PATCH 4/5] docs(foundations): refine typography Storybook catalog
 and text-link token

Align Typography foundations with DESIGN.md (click-to-copy rows, font-code
meta), move catalog data into Storybook, restore from-tokens helper, and
update text-link border-radius and motion-aligned transition in theme dist.

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../components/TypographyPreview.vue          | 124 +++++++-----------
 .../src/foundations/data/typography.js        |  50 ++++++-
 .../src/foundations/utils/from-tokens.js      | 105 +++++++++++++++
 .../stories/foundations/Typography.stories.js |   4 +-
 packages/theme/dist/v3/globals.css            |   5 +-
 packages/theme/dist/v3/globals.scss           |   5 +-
 packages/theme/dist/v4/globals.css            |   5 +-
 packages/theme/dist/v4/globals.scss           |   5 +-
 packages/theme/src/tokens/index.js            |   6 +-
 .../theme/src/tokens/semantic/texts.data.js   |  37 +-----
 10 files changed, 218 insertions(+), 128 deletions(-)
 create mode 100644 apps/storybook/src/foundations/utils/from-tokens.js

diff --git a/apps/storybook/src/foundations/components/TypographyPreview.vue b/apps/storybook/src/foundations/components/TypographyPreview.vue
index f1e18e0d3..37096e418 100644
--- a/apps/storybook/src/foundations/components/TypographyPreview.vue
+++ b/apps/storybook/src/foundations/components/TypographyPreview.vue
@@ -1,21 +1,14 @@
 <script setup>
-import { computed, ref } from 'vue'
-import { typographyCatalog, typographyLinkDemo } from '@aziontech/theme/tokens/semantic/texts.data'
-import { useViewport } from '../composables/useViewport.js'
+import { ref } from 'vue'
 
-const { breakpoint } = useViewport()
-
-const viewportTitle = computed(() => {
-  if (breakpoint.value === 'tablet') return 'Tablet'
-  if (breakpoint.value === 'mobile') return 'Mobile'
-  return 'Desktop'
-})
+import { typographyCatalog, typographyLinkDemo } from '../data/typography.js'
 
 const copiedKey = ref(null)
 let copyTimeout = null
 
-function copyToClipboard(text, key) {
-  navigator.clipboard?.writeText(text).catch(() => {})
+function copyToClipboard(value, key) {
+  if (!value) return
+  navigator.clipboard?.writeText(value).catch(() => {})
   copiedKey.value = key
   if (copyTimeout) clearTimeout(copyTimeout)
   copyTimeout = setTimeout(() => {
@@ -30,75 +23,60 @@ function isCopied(key) {
 
 <template>
   <div
-    class="flex w-full flex-col gap-[var(--spacing-xs)] rounded-[var(--shape-elements)] bg-[var(--bg-canvas)] p-[var(--spacing-xs)]"
+    class="flex w-full flex-col gap-[var(--spacing-sm)] rounded-[var(--shape-elements)] bg-[var(--bg-canvas)] p-[var(--spacing-xs)]"
   >
-    <header
-      class="flex w-full items-start rounded-[var(--shape-elements)] bg-[var(--bg-canvas)] p-[var(--spacing-lg)]"
-    >
-      <p class="text-heading-xl m-0 whitespace-nowrap text-[var(--text-default)]">
-        {{ viewportTitle }}
-      </p>
-    </header>
-
-    <div
+    <article
       v-for="item in typographyCatalog"
       :key="item.className"
-      class="flex w-full shrink-0 flex-col gap-[var(--spacing-xs)] rounded-[var(--shape-elements)] bg-[var(--bg-surface)] p-[var(--spacing-lg)]"
+      class="w-full min-w-0 cursor-pointer overflow-hidden rounded-[var(--shape-card)] border border-[var(--border-default)] bg-[var(--bg-surface)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring-color)] focus-visible:ring-offset-1 focus-visible:ring-offset-[var(--bg-canvas)]"
+      role="button"
+      tabindex="0"
+      :title="isCopied(item.className) ? 'Copied!' : 'Copy class name'"
+      @click="copyToClipboard(item.className, item.className)"
+      @keydown.enter.prevent="copyToClipboard(item.className, item.className)"
+      @keydown.space.prevent="copyToClipboard(item.className, item.className)"
     >
-      <button
-        type="button"
-        class="group inline-flex w-fit cursor-pointer items-center gap-1.5 border-none bg-transparent p-0 font-inherit"
-        :title="`Copy: ${item.className}`"
-        @click="copyToClipboard(item.className, item.className)"
-      >
-        <code
-          class="font-code w-fit rounded border border-white/15 bg-white/[0.07] px-1.5 py-0.5 text-[11px] text-code"
-        >
-          {{ item.className }}
-        </code>
-        <i
-          :class="[
-            'pi text-[10px] transition-opacity duration-100',
-            isCopied(item.className)
-              ? 'pi-check text-success'
-              : 'pi-copy opacity-0 group-hover:opacity-50'
-          ]"
-        />
-      </button>
+      <div class="flex min-h-24 w-full items-center px-[var(--spacing-lg)] py-[var(--spacing-md)]">
+        <p :class="[item.className, 'm-0 w-full break-words text-[var(--text-default)]']">
+          {{ item.sample }}
+        </p>
+      </div>
 
-      <p :class="[item.className, 'm-0 break-words text-[var(--text-default)]']">
-        {{ item.styleLabel }}
-      </p>
-    </div>
+      <div
+        class="flex items-center justify-between gap-[var(--spacing-xs)] bg-[var(--bg-mask)] px-[var(--spacing-sm)] py-[var(--spacing-xs)] font-code"
+      >
+        <span class="truncate text-body-xs text-[var(--text-muted)]">{{
+          isCopied(item.className) ? 'Copied' : item.className
+        }}</span>
+      </div>
+    </article>
 
-    <div
-      class="flex w-full shrink-0 flex-col gap-[var(--spacing-xs)] rounded-[var(--shape-elements)] bg-[var(--bg-surface)] p-[var(--spacing-lg)]"
+    <article
+      class="w-full min-w-0 cursor-pointer overflow-hidden rounded-[var(--shape-card)] border border-[var(--border-default)] bg-[var(--bg-surface)] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--ring-color)] focus-visible:ring-offset-1 focus-visible:ring-offset-[var(--bg-canvas)]"
+      role="button"
+      tabindex="0"
+      :title="isCopied('text-link') ? 'Copied!' : 'Copy class name'"
+      @click="copyToClipboard(typographyLinkDemo.linkClass, 'text-link')"
+      @keydown.enter.prevent="copyToClipboard(typographyLinkDemo.linkClass, 'text-link')"
+      @keydown.space.prevent="copyToClipboard(typographyLinkDemo.linkClass, 'text-link')"
     >
-      <button
-        type="button"
-        class="group inline-flex w-fit cursor-pointer items-center gap-1.5 border-none bg-transparent p-0 font-inherit"
-        :title="`Copy: ${typographyLinkDemo.linkClass}`"
-        @click="copyToClipboard(typographyLinkDemo.linkClass, typographyLinkDemo.linkClass)"
-      >
-        <code
-          class="font-code w-fit rounded border border-white/15 bg-white/[0.07] px-1.5 py-0.5 text-[11px] text-code"
+      <div class="flex min-h-24 w-full items-center px-[var(--spacing-lg)] py-[var(--spacing-md)]">
+        <p
+          :class="[typographyLinkDemo.parentClass, 'm-0 w-full break-words text-[var(--text-default)]']"
         >
-          {{ typographyLinkDemo.linkClass }}
-        </code>
-        <i
-          :class="[
-            'pi text-[10px] transition-opacity duration-100',
-            isCopied(typographyLinkDemo.linkClass)
-              ? 'pi-check text-success'
-              : 'pi-copy opacity-0 group-hover:opacity-50'
-          ]"
-        />
-      </button>
+          {{ typographyLinkDemo.beforeLink }}
+          <span :class="typographyLinkDemo.linkClass">{{ typographyLinkDemo.linkLabel }}</span
+          >{{ typographyLinkDemo.afterLink }}
+        </p>
+      </div>
 
-      <p :class="[typographyLinkDemo.parentClass, 'm-0 break-words text-[var(--text-default)]']">
-        Typography/Body/md with
-        <a href="#" class="text-link" @click.prevent>{{ typographyLinkDemo.linkLabel }}</a>
-      </p>
-    </div>
+      <div
+        class="flex items-center justify-between gap-[var(--spacing-xs)] bg-[var(--bg-mask)] px-[var(--spacing-sm)] py-[var(--spacing-xs)] font-code"
+      >
+        <span class="truncate text-body-xs text-[var(--text-muted)]">{{
+          isCopied('text-link') ? 'Copied' : typographyLinkDemo.linkClass
+        }}</span>
+      </div>
+    </article>
   </div>
 </template>
diff --git a/apps/storybook/src/foundations/data/typography.js b/apps/storybook/src/foundations/data/typography.js
index d03e378a1..d0a2c189b 100644
--- a/apps/storybook/src/foundations/data/typography.js
+++ b/apps/storybook/src/foundations/data/typography.js
@@ -1,12 +1,50 @@
 /**
- * Typography catalog — sourced from packages/theme/src/tokens/semantic/texts.data.js
+ * Storybook typography catalog — class list from `.claude/docs/DESIGN.md` § Available text styles.
+ * Token values compile from `packages/theme/src/tokens/semantic/texts.data.js` via `build-tokens.mjs`.
  */
+
+/** @typedef {{ className: string; sample: string }} TypographyCatalogItem */
+
+/** @type {TypographyCatalogItem[]} */
+export const typographyCatalog = [
+  { className: 'text-big-number-lg', sample: 'Big number lg' },
+  { className: 'text-big-number-md', sample: 'Big number md' },
+  { className: 'text-big-number-sm', sample: 'Big number sm' },
+  { className: 'text-heading-2xl', sample: 'Heading 2xl' },
+  { className: 'text-heading-xl', sample: 'Heading xl' },
+  { className: 'text-heading-lg', sample: 'Heading lg' },
+  { className: 'text-heading-md', sample: 'Heading md' },
+  { className: 'text-heading-sm', sample: 'Heading sm' },
+  { className: 'text-body-lg', sample: 'Body lg' },
+  { className: 'text-body-md', sample: 'Body md' },
+  { className: 'text-body-sm', sample: 'Body sm' },
+  { className: 'text-body-xs', sample: 'Body xs' },
+  { className: 'text-body-xxs', sample: 'Body xxs' },
+  { className: 'text-label-lg', sample: 'Label lg' },
+  { className: 'text-label-md', sample: 'Label md' },
+  { className: 'text-label-sm', sample: 'Label sm' },
+  { className: 'text-overline-md', sample: 'Overline md' },
+  { className: 'text-overline-sm', sample: 'Overline sm' },
+  { className: 'text-overline-xs', sample: 'Overline xs' },
+  { className: 'text-button-lg', sample: 'Button lg' },
+  { className: 'text-button-md', sample: 'Button md' }
+]
+
+/** Inline link demo — DESIGN.md § Inline links vs navigation `Link` */
+export const typographyLinkDemo = {
+  parentClass: 'text-body-md',
+  beforeLink: 'Read the ',
+  linkClass: 'text-link',
+  linkLabel: 'documentation',
+  afterLink: '.'
+}
+
 export {
-  typographyTokens,
-  typographyGroups,
+  breakpointRows,
+  breakpoints,
   buildTypographyTokens,
   getActiveBreakpoint,
   resolveResponsiveValue,
-  breakpoints,
-  breakpointRows,
-} from '../utils/from-tokens.js';
+  typographyGroups,
+  typographyTokens
+} from '../utils/from-tokens.js'
diff --git a/apps/storybook/src/foundations/utils/from-tokens.js b/apps/storybook/src/foundations/utils/from-tokens.js
new file mode 100644
index 000000000..8b5bd9079
--- /dev/null
+++ b/apps/storybook/src/foundations/utils/from-tokens.js
@@ -0,0 +1,105 @@
+import { textsData } from '@aziontech/theme/tokens/semantic/texts.data';
+const spacingsData = {
+  'spacing-xxl': { _: '2rem', sm: '4rem', xl: '6rem' },
+  'spacing-xl': { _: '1.5rem', sm: '2rem', xl: '3rem' },
+  'spacing-lg': { _: '1rem', sm: '1.5rem' },
+  'spacing-md': { _: '1rem' },
+  'spacing-sm': { _: '0.75rem' },
+  'spacing-xs': { _: '0.5rem' },
+  'spacing-xxs': { _: '0.25rem' },
+};
+
+
+export const breakpoints = {
+  _: 0,
+  sm: 640,
+  md: 768,
+  lg: 1024,
+  xl: 1280,
+  '2xl': 1536,
+};
+
+export const breakpointRows = [
+  { key: '_', label: 'Base' },
+  { key: 'sm', label: 'sm >=640' },
+  { key: 'md', label: 'md >=768' },
+  { key: 'lg', label: 'lg >=1024' },
+  { key: 'xl', label: 'xl >=1280' },
+  { key: '2xl', label: '2xl >=1536' },
+];
+
+const orderedKeys = ['_', 'sm', 'md', 'lg', 'xl', '2xl'];
+
+export function getActiveBreakpoint(width) {
+  if (width >= breakpoints['2xl']) return '2xl';
+  if (width >= breakpoints.xl) return 'xl';
+  if (width >= breakpoints.lg) return 'lg';
+  if (width >= breakpoints.md) return 'md';
+  if (width >= breakpoints.sm) return 'sm';
+  return '_';
+}
+
+export function resolveResponsiveValue(value, width) {
+  if (typeof value !== 'object' || value === null) return value;
+
+  const active = getActiveBreakpoint(width);
+  const activeIndex = orderedKeys.indexOf(active);
+
+  for (let i = activeIndex; i >= 0; i -= 1) {
+    const key = orderedKeys[i];
+    if (value[key] !== undefined) return value[key];
+  }
+
+  return value._;
+}
+
+export function buildSpacingTokens() {
+  return Object.entries(spacingsData).map(([name, responsive]) => ({
+    name,
+    label: name.replace('spacing-', '').toUpperCase(),
+    cssVar: `--${name}`,
+    usageExample: `var(--${name})`,
+    description: `Responsive spacing token ${name}.`,
+    responsive,
+  }));
+}
+
+export const spacingTokens = buildSpacingTokens();
+export const spacingGroups = [
+  {
+    category: 'semantic',
+    label: 'Semantic spacing tokens',
+    description: 'Spacing values mapped to responsive breakpoints.',
+    tokens: spacingTokens,
+  },
+];
+
+export function buildTypographyTokens() {
+  return Object.entries(textsData).map(([name, values]) => ({
+    name,
+    label: name,
+    usageClass: `.${name}`,
+    sample: 'The quick brown fox jumps over the lazy dog.',
+    description: `Semantic text token ${name}.`,
+    fontFamily: values.fontFamily ?? 'var(--font-family, inherit)',
+    responsive:
+      typeof values.fontSize === 'object'
+        ? Object.fromEntries(
+            Object.entries(values.fontSize).map(([key, fontSize]) => [
+              key,
+              { fontSize, lineHeight: values.lineHeight ?? 'normal' },
+            ]),
+          )
+        : { _: { fontSize: values.fontSize ?? 'inherit', lineHeight: values.lineHeight ?? 'normal' } },
+  }));
+}
+
+export const typographyTokens = buildTypographyTokens();
+export const typographyGroups = [
+  {
+    category: 'semantic',
+    label: 'Semantic text tokens',
+    description: 'Typography classes generated from theme text tokens.',
+    tokens: typographyTokens,
+  },
+];
diff --git a/apps/storybook/src/stories/foundations/Typography.stories.js b/apps/storybook/src/stories/foundations/Typography.stories.js
index f7d0efcec..adf808b08 100644
--- a/apps/storybook/src/stories/foundations/Typography.stories.js
+++ b/apps/storybook/src/stories/foundations/Typography.stories.js
@@ -19,8 +19,8 @@ export default {
   },
 };
 
-export const Catalog = {
-  name: 'Catalog',
+export const Overview = {
+  name: 'Overview',
   render: () => ({
     components: { PageContainer, PageHeader, TypographyPreview },
     template: /* html */ `
diff --git a/packages/theme/dist/v3/globals.css b/packages/theme/dist/v3/globals.css
index 497cbb139..61566e4d3 100644
--- a/packages/theme/dist/v3/globals.css
+++ b/packages/theme/dist/v3/globals.css
@@ -531,7 +531,8 @@
     --text-link-font-size: inherit;
     --text-link-line-height: inherit;
     --text-link-color: var(--text-link);
-    --text-link-transition: color 150ms ease-out;
+    --text-link-border-radius: var(--shape-elements);
+    --text-link-transition: all 110ms cubic-bezier(0.39, 0.57, 0.56, 1);
 
     /* ── Semantic colors ── */
     --text-default: #141414;
@@ -829,7 +830,7 @@
   .text-overline-xs { font-family: var(--text-overline-xs-font-family); font-size: var(--text-overline-xs-font-size); line-height: var(--text-overline-xs-line-height); letter-spacing: var(--text-overline-xs-letter-spacing); text-transform: var(--text-overline-xs-text-transform); }
   .text-button-lg { font-family: var(--text-button-lg-font-family); font-size: var(--text-button-lg-font-size); font-weight: var(--text-button-lg-font-weight); line-height: var(--text-button-lg-line-height); letter-spacing: var(--text-button-lg-letter-spacing); }
   .text-button-md { font-family: var(--text-button-md-font-family); font-size: var(--text-button-md-font-size); font-weight: var(--text-button-md-font-weight); line-height: var(--text-button-md-line-height); letter-spacing: var(--text-button-md-letter-spacing); }
-  .text-link { font-size: var(--text-link-font-size); line-height: var(--text-link-line-height); color: var(--text-link-color); transition: var(--text-link-transition); }
+  .text-link { font-size: var(--text-link-font-size); line-height: var(--text-link-line-height); color: var(--text-link-color); border-radius: var(--text-link-border-radius); transition: var(--text-link-transition); }
   .text-link:hover { color: var(--text-link-hover); text-decoration: underline; }
   .text-link:focus-visible { outline: 2px solid var(--ring-color); outline-offset: 2px; }
   @media (prefers-reduced-motion: reduce) {
diff --git a/packages/theme/dist/v3/globals.scss b/packages/theme/dist/v3/globals.scss
index 497cbb139..61566e4d3 100644
--- a/packages/theme/dist/v3/globals.scss
+++ b/packages/theme/dist/v3/globals.scss
@@ -531,7 +531,8 @@
     --text-link-font-size: inherit;
     --text-link-line-height: inherit;
     --text-link-color: var(--text-link);
-    --text-link-transition: color 150ms ease-out;
+    --text-link-border-radius: var(--shape-elements);
+    --text-link-transition: all 110ms cubic-bezier(0.39, 0.57, 0.56, 1);
 
     /* ── Semantic colors ── */
     --text-default: #141414;
@@ -829,7 +830,7 @@
   .text-overline-xs { font-family: var(--text-overline-xs-font-family); font-size: var(--text-overline-xs-font-size); line-height: var(--text-overline-xs-line-height); letter-spacing: var(--text-overline-xs-letter-spacing); text-transform: var(--text-overline-xs-text-transform); }
   .text-button-lg { font-family: var(--text-button-lg-font-family); font-size: var(--text-button-lg-font-size); font-weight: var(--text-button-lg-font-weight); line-height: var(--text-button-lg-line-height); letter-spacing: var(--text-button-lg-letter-spacing); }
   .text-button-md { font-family: var(--text-button-md-font-family); font-size: var(--text-button-md-font-size); font-weight: var(--text-button-md-font-weight); line-height: var(--text-button-md-line-height); letter-spacing: var(--text-button-md-letter-spacing); }
-  .text-link { font-size: var(--text-link-font-size); line-height: var(--text-link-line-height); color: var(--text-link-color); transition: var(--text-link-transition); }
+  .text-link { font-size: var(--text-link-font-size); line-height: var(--text-link-line-height); color: var(--text-link-color); border-radius: var(--text-link-border-radius); transition: var(--text-link-transition); }
   .text-link:hover { color: var(--text-link-hover); text-decoration: underline; }
   .text-link:focus-visible { outline: 2px solid var(--ring-color); outline-offset: 2px; }
   @media (prefers-reduced-motion: reduce) {
diff --git a/packages/theme/dist/v4/globals.css b/packages/theme/dist/v4/globals.css
index b6f2b995e..a8b86df70 100644
--- a/packages/theme/dist/v4/globals.css
+++ b/packages/theme/dist/v4/globals.css
@@ -526,7 +526,8 @@
   --text-link-font-size: inherit;
   --text-link-line-height: inherit;
   --text-link-color: var(--text-link);
-  --text-link-transition: color 150ms ease-out;
+  --text-link-border-radius: var(--shape-elements);
+  --text-link-transition: all 110ms cubic-bezier(0.39, 0.57, 0.56, 1);
 
   @media (min-width: 640px) {
     --container-px: 2.5rem;
@@ -609,7 +610,7 @@
   .text-overline-xs { font-family: var(--text-overline-xs-font-family); font-size: var(--text-overline-xs-font-size); line-height: var(--text-overline-xs-line-height); letter-spacing: var(--text-overline-xs-letter-spacing); text-transform: var(--text-overline-xs-text-transform); }
   .text-button-lg { font-family: var(--text-button-lg-font-family); font-size: var(--text-button-lg-font-size); font-weight: var(--text-button-lg-font-weight); line-height: var(--text-button-lg-line-height); letter-spacing: var(--text-button-lg-letter-spacing); }
   .text-button-md { font-family: var(--text-button-md-font-family); font-size: var(--text-button-md-font-size); font-weight: var(--text-button-md-font-weight); line-height: var(--text-button-md-line-height); letter-spacing: var(--text-button-md-letter-spacing); }
-  .text-link { font-size: var(--text-link-font-size); line-height: var(--text-link-line-height); color: var(--text-link-color); transition: var(--text-link-transition); }
+  .text-link { font-size: var(--text-link-font-size); line-height: var(--text-link-line-height); color: var(--text-link-color); border-radius: var(--text-link-border-radius); transition: var(--text-link-transition); }
   .text-link:hover { color: var(--text-link-hover); text-decoration: underline; }
   .text-link:focus-visible { outline: 2px solid var(--ring-color); outline-offset: 2px; }
   @media (prefers-reduced-motion: reduce) {
diff --git a/packages/theme/dist/v4/globals.scss b/packages/theme/dist/v4/globals.scss
index b6f2b995e..a8b86df70 100644
--- a/packages/theme/dist/v4/globals.scss
+++ b/packages/theme/dist/v4/globals.scss
@@ -526,7 +526,8 @@
   --text-link-font-size: inherit;
   --text-link-line-height: inherit;
   --text-link-color: var(--text-link);
-  --text-link-transition: color 150ms ease-out;
+  --text-link-border-radius: var(--shape-elements);
+  --text-link-transition: all 110ms cubic-bezier(0.39, 0.57, 0.56, 1);
 
   @media (min-width: 640px) {
     --container-px: 2.5rem;
@@ -609,7 +610,7 @@
   .text-overline-xs { font-family: var(--text-overline-xs-font-family); font-size: var(--text-overline-xs-font-size); line-height: var(--text-overline-xs-line-height); letter-spacing: var(--text-overline-xs-letter-spacing); text-transform: var(--text-overline-xs-text-transform); }
   .text-button-lg { font-family: var(--text-button-lg-font-family); font-size: var(--text-button-lg-font-size); font-weight: var(--text-button-lg-font-weight); line-height: var(--text-button-lg-line-height); letter-spacing: var(--text-button-lg-letter-spacing); }
   .text-button-md { font-family: var(--text-button-md-font-family); font-size: var(--text-button-md-font-size); font-weight: var(--text-button-md-font-weight); line-height: var(--text-button-md-line-height); letter-spacing: var(--text-button-md-letter-spacing); }
-  .text-link { font-size: var(--text-link-font-size); line-height: var(--text-link-line-height); color: var(--text-link-color); transition: var(--text-link-transition); }
+  .text-link { font-size: var(--text-link-font-size); line-height: var(--text-link-line-height); color: var(--text-link-color); border-radius: var(--text-link-border-radius); transition: var(--text-link-transition); }
   .text-link:hover { color: var(--text-link-hover); text-decoration: underline; }
   .text-link:focus-visible { outline: 2px solid var(--ring-color); outline-offset: 2px; }
   @media (prefers-reduced-motion: reduce) {
diff --git a/packages/theme/src/tokens/index.js b/packages/theme/src/tokens/index.js
index 09fcc4725..9038ae53d 100644
--- a/packages/theme/src/tokens/index.js
+++ b/packages/theme/src/tokens/index.js
@@ -5,9 +5,5 @@
 export { createCssVars, cssVarsString, injectCssVars } from '../scripts/css-vars.js';
 export * from './primitives/colors/colors.js';
 export * from './semantic/colors.js';
-export {
-  textsData,
-  typographyCatalog,
-  typographyLinkDemo
-} from './semantic/texts.data.js';
+export { textsData } from './semantic/texts.data.js';
 export * from './theme.js';
diff --git a/packages/theme/src/tokens/semantic/texts.data.js b/packages/theme/src/tokens/semantic/texts.data.js
index f9b46659b..448d70706 100644
--- a/packages/theme/src/tokens/semantic/texts.data.js
+++ b/packages/theme/src/tokens/semantic/texts.data.js
@@ -128,7 +128,8 @@ export const textsData = {
     fontSize: 'inherit',
     lineHeight: 'inherit',
     color: 'var(--text-link)',
-    transition: 'all 150ms ease-out',
+    borderRadius: 'var(--shape-elements)',
+    transition: 'all 110ms cubic-bezier(0.39, 0.57, 0.56, 1)',
     states: {
       hover: {
         color: 'var(--text-link-hover)',
@@ -142,36 +143,4 @@ export const textsData = {
   }
 }
 
-/** Display order for type catalog UIs (Storybook, docs). */
-export const typographyCatalog = [
-  { styleLabel: 'Typography/Big Number/lg', className: 'text-big-number-lg' },
-  { styleLabel: 'Typography/Big Number/md', className: 'text-big-number-md' },
-  { styleLabel: 'Typography/Big Number/sm', className: 'text-big-number-sm' },
-  { styleLabel: 'Typography/Heading/2xl', className: 'text-heading-2xl' },
-  { styleLabel: 'Typography/Heading/xl', className: 'text-heading-xl' },
-  { styleLabel: 'Typography/Heading/lg', className: 'text-heading-lg' },
-  { styleLabel: 'Typography/Heading/md', className: 'text-heading-md' },
-  { styleLabel: 'Typography/Heading/sm', className: 'text-heading-sm' },
-  { styleLabel: 'Typography/Body/lg', className: 'text-body-lg' },
-  { styleLabel: 'Typography/Body/md', className: 'text-body-md' },
-  { styleLabel: 'Typography/Body/sm', className: 'text-body-sm' },
-  { styleLabel: 'Typography/Body/xs', className: 'text-body-xs' },
-  { styleLabel: 'Typography/Body/xxs', className: 'text-body-xxs' },
-  { styleLabel: 'Typography/Label/lg', className: 'text-label-lg' },
-  { styleLabel: 'Typography/Label/md', className: 'text-label-md' },
-  { styleLabel: 'Typography/Label/sm', className: 'text-label-sm' },
-  { styleLabel: 'Typography/Overline/md', className: 'text-overline-md' },
-  { styleLabel: 'Typography/Overline/sm', className: 'text-overline-sm' },
-  { styleLabel: 'Typography/Overline/xs', className: 'text-overline-xs' },
-  { styleLabel: 'Typography/Button/lg', className: 'text-button-lg' },
-  { styleLabel: 'Typography/Button/md', className: 'text-button-md' }
-]
-
-/** Inline link demo row (parent body + `text-link` anchor). */
-export const typographyLinkDemo = {
-  parentClass: 'text-body-md',
-  linkLabel: 'Typography/Link',
-  linkClass: 'text-link'
-}
-
-export default { textsData, typographyCatalog, typographyLinkDemo }
+export default { textsData }

From ea88b19bcbbc60441b241c3a321ad1420098f3f0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Isaque=20B=C3=B6ck?= <isaquebockdos@gmail.com>
Date: Tue, 2 Jun 2026 14:34:44 -0300
Subject: [PATCH 5/5] Potential fix for pull request finding 'Property access
 on null or undefined'

Co-authored-by: Copilot Autofix powered by AI <223894421+github-code-quality[bot]@users.noreply.github.com>
---
 .../src/foundations/components/ColorPlayground.vue          | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/apps/storybook/src/foundations/components/ColorPlayground.vue b/apps/storybook/src/foundations/components/ColorPlayground.vue
index 840661ff0..76906e060 100644
--- a/apps/storybook/src/foundations/components/ColorPlayground.vue
+++ b/apps/storybook/src/foundations/components/ColorPlayground.vue
@@ -2,6 +2,8 @@
 import { ref, computed, onMounted, onUnmounted } from 'vue';
 import { playgroundColorTokens } from '../data/colors.js';
 
+const tokens = Array.isArray(playgroundColorTokens) ? playgroundColorTokens : [];
+
 const CATEGORIES = [
   { key: 'theme', label: 'Theme', filter: (t) => t.category === 'theme' },
   { key: 'background', label: 'Background', filter: (t) => t.category === 'background' },
@@ -26,7 +28,7 @@ onMounted(() => {
   observer.observe(document.documentElement, { attributes: true, attributeFilter: ['class'] });
   observer.observe(document.body, { attributes: true, attributeFilter: ['class'] });
 
-  const first = playgroundColorTokens.find((t) => t.name === 'primary') ?? playgroundColorTokens[0];
+  const first = tokens.find((t) => t.name === 'primary') ?? tokens[0];
   if (first) selectedTokenName.value = first.name;
 });
 
@@ -36,7 +38,7 @@ onUnmounted(() => {
 
 const activeTokens = computed(() => {
   const cat = CATEGORIES.find((c) => c.key === selectedCategory.value);
-  return cat ? playgroundColorTokens.filter(cat.filter) : playgroundColorTokens;
+  return cat ? tokens.filter(cat.filter) : tokens;
 });
 
 const selectedToken = computed(