From add667fe009c2c8a0691d3425242333947f24467 Mon Sep 17 00:00:00 2001
From: Max Rozdobudko <max.rozdobudko@gmail.com>
Date: Sat, 21 Feb 2026 00:13:56 +0200
Subject: [PATCH] Warn when token names conflict with SwiftUI built-in
 ShapeStyle properties

Highlights conflicting tokens (e.g. "primary", "background") with a red
outline and warning icon in the tag, and shows an inline hint in the
popover prompting users to set a custom style name override.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 .../pages/src/components/TokenPopover.svelte  | 10 +++++++
 .github/pages/src/components/TokenTag.svelte  | 11 ++++++-
 .github/pages/src/lib/validation.js           | 27 +++++++++++++++++
 .github/pages/src/styles/app.css              | 30 +++++++++++++++++++
 4 files changed, 77 insertions(+), 1 deletion(-)
 create mode 100644 .github/pages/src/lib/validation.js

diff --git a/.github/pages/src/components/TokenPopover.svelte b/.github/pages/src/components/TokenPopover.svelte
index c67a0ea..2f0657d 100644
--- a/.github/pages/src/components/TokenPopover.svelte
+++ b/.github/pages/src/components/TokenPopover.svelte
@@ -1,5 +1,6 @@
 <script>
   import { untrack } from 'svelte';
+  import { SWIFTUI_BUILTIN_STYLES } from '../lib/validation.js';
 
   let { token, tokenProperties = [], onupdate, onclose } = $props();
 
@@ -20,6 +21,10 @@
     onupdate(key, raw || token.name);
   }
 
+  let showWarning = $derived(
+    SWIFTUI_BUILTIN_STYLES.has(values.style || token.name) && !values.style
+  );
+
   function handleKeydown(e) {
     if (e.key === 'Escape') onclose();
   }
@@ -31,6 +36,11 @@
     <span class="popover-title">{token.name}</span>
     <button class="popover-close" onclick={onclose} aria-label="Close">&times;</button>
   </div>
+  {#if showWarning}
+    <div class="popover-warning">
+      Shadows SwiftUI's built-in <code>.{token.name}</code> — set a custom style name below.
+    </div>
+  {/if}
   {#each tokenProperties as prop}
     <div class="popover-field">
       <label for="token-prop-{prop.key}">{prop.key}</label>
diff --git a/.github/pages/src/components/TokenTag.svelte b/.github/pages/src/components/TokenTag.svelte
index e88133a..93d9ede 100644
--- a/.github/pages/src/components/TokenTag.svelte
+++ b/.github/pages/src/components/TokenTag.svelte
@@ -1,5 +1,6 @@
 <script>
   import TokenPopover from './TokenPopover.svelte';
+  import { hasBuiltinConflict } from '../lib/validation.js';
 
   let { token, tokenProperties = [], onremove, onupdate } = $props();
 
@@ -14,10 +15,18 @@
   }
 
   let hasOverride = $derived(token.name !== token.style);
+  let hasConflict = $derived(hasBuiltinConflict(token));
 </script>
 
-<span class="token-tag" class:has-override={hasOverride}>
+<span class="token-tag" class:has-override={hasOverride} class:has-conflict={hasConflict}>
   <span class="tag-name">{token.name}</span>
+  {#if hasConflict}
+    <span class="tag-warning" title="Shadows SwiftUI's built-in .{token.name} — open to set a custom style name">
+      <svg width="14" height="14" viewBox="0 0 16 16" fill="currentColor">
+        <path d="M8.982 1.566a1.13 1.13 0 00-1.96 0L.165 13.233c-.457.778.091 1.767.98 1.767h13.713c.889 0 1.438-.99.98-1.767L8.982 1.566zM8 5c.535 0 .954.462.9.995l-.35 3.507a.552.552 0 01-1.1 0L7.1 5.995A.905.905 0 018 5zm.002 6a1 1 0 110 2 1 1 0 010-2z"/>
+      </svg>
+    </span>
+  {/if}
   <button class="tag-btn info-btn" onclick={togglePopover} aria-label="Edit token properties">
     <svg width="14" height="14" viewBox="0 0 16 16" fill="currentColor">
       <path d="M8 1a7 7 0 100 14A7 7 0 008 1zm0 2.5a1 1 0 110 2 1 1 0 010-2zM6.5 7h2l.5 0v5h-1V8h-1.5V7z"/>
diff --git a/.github/pages/src/lib/validation.js b/.github/pages/src/lib/validation.js
new file mode 100644
index 0000000..fab3438
--- /dev/null
+++ b/.github/pages/src/lib/validation.js
@@ -0,0 +1,27 @@
+/** SwiftUI built-in ShapeStyle static properties that will conflict with generated extensions. */
+export const SWIFTUI_BUILTIN_STYLES = new Set([
+  'primary',
+  'secondary',
+  'tertiary',
+  'quaternary',
+  'background',
+  'foreground',
+  'selection',
+  'separator',
+  'tint',
+  'placeholder',
+  'fill',
+  'link',
+  'ultraThinMaterial',
+  'thinMaterial',
+  'regularMaterial',
+  'thickMaterial',
+  'ultraThickMaterial',
+  'bar',
+  'windowBackground',
+]);
+
+/** Returns true when a token's effective style name shadows a SwiftUI built-in. */
+export function hasBuiltinConflict(token) {
+  return token.name === token.style && SWIFTUI_BUILTIN_STYLES.has(token.style);
+}
diff --git a/.github/pages/src/styles/app.css b/.github/pages/src/styles/app.css
index 66f1276..fab7105 100644
--- a/.github/pages/src/styles/app.css
+++ b/.github/pages/src/styles/app.css
@@ -312,6 +312,21 @@ section h2 {
   background: var(--color-tag-override);
 }
 
+.token-tag.has-conflict {
+  background: var(--color-danger-light);
+  outline: 1px solid var(--color-danger);
+}
+
+.tag-warning {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 18px;
+  height: 18px;
+  color: var(--color-danger);
+  cursor: help;
+}
+
 .tag-name {
   padding: 0 0.25rem 0 0.5rem;
   font-family: var(--font-mono);
@@ -440,6 +455,21 @@ section h2 {
   color: var(--color-text);
 }
 
+.popover-warning {
+  background: var(--color-danger-light);
+  color: var(--color-danger);
+  font-size: 0.75rem;
+  line-height: 1.4;
+  padding: 0.4rem 0.5rem;
+  border-radius: var(--radius);
+  margin-bottom: 0.5rem;
+}
+
+.popover-warning code {
+  font-family: var(--font-mono);
+  font-weight: 600;
+}
+
 .popover-field {
   display: flex;
   flex-direction: column;