@utopia-studio-design/design-system-cli 0.3.0 → 0.3.2

package/data/manifests/components.json

@@ -481,6 +481,11 @@
         "--foreground",
         "--muted-foreground",
         "--foreground-subtle",
+        "--inverse-foreground",
+        "--inverse-foreground-muted",
+        "--inverse-foreground-subtle",
+        "--inverse-hover",
+        "--inverse-focus-ring",
         "--surface-hover",
         "--radius-control",
         "--space-2",
@@ -493,7 +498,8 @@
       "useWhen": [
         "A deep page needs parent-page context",
         "Users need to understand where the current resource sits in a hierarchy",
-        "A long path may need collapsed middle items or an overflow menu"
+        "A long path may need collapsed middle items or an overflow menu",
+        "A top bar on --surface-inverse needs Ceramic-owned link, separator, current-page, hover, and focus colors"
       ],
       "avoidWhen": [
         "Primary navigation is needed; use Top Nav, Side Nav, or Navigation Menu",
@@ -508,6 +514,7 @@
       "ai": {
         "props": {
           "aria-label": "Required localized label for the breadcrumb navigation landmark.",
+          "variant": "Use default for ordinary surfaces and inverse when the Breadcrumb is placed on --surface-inverse.",
           "Breadcrumb": "Root nav landmark. Keep aria-label descriptive and localized when needed.",
           "BreadcrumbList": "Ordered list wrapper for breadcrumb items and separators.",
           "BreadcrumbItem": "List item wrapper for link, current page, or collapsed menu trigger.",
@@ -699,7 +706,10 @@
       ],
       "ai": {
         "props": {
-          "motion": "Optional boolean. Defaults to the MotionProvider policy and disables this component pattern when false."
+          "motion": "Optional boolean. Defaults to the MotionProvider policy and disables this component pattern when false.",
+          "contentAlign": "Use 'start' for leading-aligned labels, 'center' for the default action layout, or 'between' to pin endContent to the logical inline end.",
+          "startContent": "Optional leading icon or content slot with package-owned alignment.",
+          "endContent": "Optional trailing content slot. With contentAlign='between', it remains pinned while the label truncates."
         }
       }
     },
@@ -2980,8 +2990,8 @@
       "name": "Native Select",
       "category": "Forms",
       "status": "available",
-      "packageImport": "import { NativeSelect, NativeSelectOptGroup, NativeSelectOption } from '@utopia-studio-design/design-system/ShadcnPrimitives';",
-      "sourcePath": "packages/design-system/src/components/ShadcnPrimitives.tsx",
+      "packageImport": "import { NativeSelect, NativeSelectOptGroup, NativeSelectOption } from '@utopia-studio-design/design-system/Forms';",
+      "sourcePath": "packages/design-system/src/components/Forms.tsx",
       "shadcnFoundation": [
         "native-select",
         "shadcn/ui registry",
@@ -3008,10 +3018,12 @@
       "avoidWhen": [
         "Searchable or async option sets",
         "Complex custom option rendering",
+        "The opened option menu must match dark, light, or popover semantic tokens; use Select, SelectTrigger, SelectContent, and SelectItem",
         "Product localization rules inside reusable component logic"
       ],
       "neverInvent": [
         "Product-owned option values or selection rules",
+        "A promise that the opened native option menu can be fully themed; the OS or browser owns that surface",
         "Production Arabic option labels not supplied by localization",
         "Left/right-only layout rules",
         "Utopia brand primitives inside reusable component logic"
@@ -3482,10 +3494,12 @@
         "--background",
         "--foreground",
         "--muted-foreground",
+        "--icon-size-sm",
         "--button-height-sm"
       ],
       "useWhen": [
         "Compact option selection",
+        "Dark, light, or branded surfaces where the opened menu must follow popover semantic tokens",
         "Longer option sets than Radio Group",
         "AI-generated forms that need explicit trigger, value, content, and item parts",
         "Grouped option lists with labels",
@@ -3617,7 +3631,7 @@
       "name": "Side Nav",
       "category": "Navigation",
       "status": "available",
-      "packageImport": "import { PanelIcon, SideNav, SideNavCollapseButton, SideNavContent, SideNavHeading, SideNavItem, SideNavNestedGroup, SideNavNestedItems, SideNavSearch, SideNavSection } from '@utopia-studio-design/design-system/Navigation';",
+      "packageImport": "import { NavigationIcon, PanelIcon, SideNav, SideNavAccount, SideNavAuxiliary, SideNavCollapseButton, SideNavCommand, SideNavContent, SideNavFooter, SideNavHeader, SideNavHeading, SideNavItem, SideNavMain, SideNavNestedGroup, SideNavNestedItems, SideNavSearch, SideNavSection, SideNavStatus, SideNavWorkspaceSwitcher } from '@utopia-studio-design/design-system/Navigation';",
       "sourcePath": "packages/design-system/src/components/Navigation.tsx",
       "shadcnFoundation": [
         "sidebar",
@@ -3641,6 +3655,8 @@
       "useWhen": [
         "Persistent docs or app navigation",
         "Grouped navigation links with current page state",
+        "An application shell needs fixed header and footer regions with only the main navigation scrolling",
+        "Search, AI commands, status, and account controls must adapt to expanded and collapsed states without app CSS overrides",
         "A navigation surface needs package-owned content, search, section, nested group, item, heading, account, and collapse composition parts",
         "A navigation surface should receive heading and search as SideNav props instead of hardcoding local wrappers",
         "AI-generated app shells that need explicit section, heading, item, nested item, search, and collapse button parts"
@@ -3654,7 +3670,7 @@
         "Raw shadcn theme colors",
         "Left/right-only layout rules",
         "Utopia brand primitives inside reusable component logic",
-        "Local CSS-only search, nested group, or content wrappers when SideNavSearch, SideNavNestedGroup, SideNavNestedItems, or SideNavContent are available"
+        "Local CSS-only search, command, account, footer, or content wrappers when the corresponding SideNav composition parts are available"
       ],
       "ai": {
         "props": {
@@ -3662,10 +3678,19 @@
           "density": "Use default for app navigation; use compact for docs/library sidebars with dense catalog lists.",
           "heading": "Optional SideNavHeading node rendered before search and navigation content.",
           "search": "Optional SideNavSearch node rendered after heading and before navigation content.",
-          "SideNavContent": "Scrollable or flexible body region for repeated SideNavSection groups.",
+          "SideNavContent": "Compatibility body region. Set layout='stack' for a flex column that supports an auto-positioned footer, or layout='grid' for the legacy grid flow.",
+          "SideNavHeader": "Fixed header region for brand, workspace, and collapse controls.",
+          "SideNavMain": "The only independently scrolling navigation region. It defaults to layout='stack' and fills remaining height.",
+          "SideNavFooter": "Bottom-pinned, bounded footer region for status and account controls.",
+          "SideNavCommand": "Full-width icon, label, and shortcut action. It derives collapsed state, accessible name, and tooltip title from SideNav context.",
+          "SideNavAccount": "Stable avatar, single-line identity, and action layout. Use asChild or trigger to compose an app-owned popover/auth trigger.",
+          "SideNavStatus": "Status indicator with label and optional description. Collapsed navigation retains the label for assistive technology and exposes a tooltip title.",
+          "SideNavWorkspaceSwitcher": "Fixed region for an app-owned organization or workspace switcher.",
+          "SideNavAuxiliary": "Fixed auxiliary action region outside the independently scrolling main navigation.",
           "SideNavSearch": "Package-owned search field for filtering navigation lists without local input styling.",
           "SideNavNestedGroup": "Groups a parent SideNavItem and its nested child collection.",
           "SideNavNestedItems": "Indented child item collection using logical inline-start spacing and border.",
+          "NavigationIcon": "Official Ceramic destination icon set. Use names such as dashboard, projects, tasks, inbox, files, analytics, team, settings, and help without importing an app icon package.",
           "PanelIcon": "Direction-neutral icon exported for SideNavCollapseButton examples. Prefer it over directional arrows unless the directional icon has an RTL mirror rule."
         },
         "arabicFriendly": "Use logical start/end spacing in nested items and let document direction control order. Closed disclosure indicators rotate toward the inline start in LTR and RTL. Preserve scroll position when the side nav collapses and expands, and do not use left/right naming in generated side navigation layouts."
@@ -3823,6 +3848,7 @@
       ],
       "ai": {
         "props": {
+          "asChild": "Use with a framework-native link such as Next.js Link so the link remains the single interactive element while SideNavItem supplies styling and state.",
           "icon": "Optional leading visual slot. Omit for text-only rows; do not add placeholder marks.",
           "depth": "Use 0 for root rows, 1 for items inside a top-level section, 2 for nested section children, and 3 only for rare deep navigation.",
           "badge": "Optional trailing count or status pill aligned to the inline end.",
@@ -3930,6 +3956,8 @@
         "--foreground",
         "--border",
         "--surface-hover",
+        "--primary",
+        "--font-size-supporting",
         "--popover-surface",
         "--radius-control",
         "--radius-surface",
@@ -3979,6 +4007,11 @@
           "SidebarTrigger",
           "useSidebar"
         ],
+        "props": {
+          "SidebarMenuButton.activeVariant": "Use background for backward compatibility, indicator for a logical inline-start current marker, or both for the marker plus background.",
+          "SidebarMenuButton.isActive": "Marks the item active and supplies aria-current=page unless the consumer provides another aria-current value.",
+          "SidebarMenuButton.tooltip": "Provides collapsed hover/focus help and an accessible name when aria-label is omitted."
+        },
         "arabicFriendly": "Use dir=rtl at the shell boundary and provide localized collapseLabel, expandLabel, overlay labels, rail labels, and tooltip strings. Logical borders, alignment, off-canvas motion, submenus, and badges mirror without changing the component API."
       }
     },
@@ -4089,6 +4122,54 @@
         "arabicFriendly": "Loading labels come from product localization. The spinner is direction-neutral and must not be mirrored."
       }
     },
+    {
+      "name": "Utopia Wordmark Loader",
+      "category": "Data Display",
+      "status": "available",
+      "packageImport": "import { UtopiaWordmarkLoader } from '@utopia-studio-design/design-system/UtopiaWordmarkLoader';",
+      "sourcePath": "packages/design-system/src/components/UtopiaWordmarkLoader.tsx",
+      "shadcnFoundation": [
+        "spinner status semantics",
+        "full-screen loading state"
+      ],
+      "fallbackToShadcn": "spinner",
+      "requiredTokens": [
+        "--brand-loader-background",
+        "--brand-loader-accent",
+        "--brand-loader-foreground",
+        "--brand-loader-size",
+        "--brand-loader-duration-enter",
+        "--brand-loader-duration-cycle",
+        "--brand-loader-duration-stagger",
+        "--brand-loader-duration-exit",
+        "--brand-loader-distance-exit"
+      ],
+      "useWhen": [
+        "A Utopia product needs a branded full-page or contained loading transition",
+        "Workspace or route loading should end as soon as the consumer loading state resolves",
+        "The Utopia Default theme is active and the stacked studio wordmark is appropriate"
+      ],
+      "avoidWhen": [
+        "Short inline pending states; use Spinner",
+        "Layout-preserving content loading; use Skeleton",
+        "A non-Utopia product theme needs its own brand mark"
+      ],
+      "neverInvent": [
+        "A timer that delays navigation after the real loading state resolves",
+        "Left/right-only layout rules",
+        "Utopia brand primitives outside this explicitly branded component contract"
+      ],
+      "ai": {
+        "props": {
+          "label": "Required localized loading text announced through role=status.",
+          "phase": "Use intro while loading and exit after the consumer loading state resolves.",
+          "fullscreen": "Defaults to true. Set false for a contained loading region.",
+          "size": "sm is the production default; md and lg are available for larger brand moments.",
+          "onExitComplete": "Called after the exit motion so the consumer can unmount the overlay."
+        },
+        "arabicFriendly": "The mark is direction-neutral and must not mirror. The localized status label is visually hidden and remains consumer-owned."
+      }
+    },
     {
       "name": "Switch",
       "category": "Forms",

package/data/manifests/motion-profiles.json

@@ -0,0 +1,121 @@
+{
+  "$schema": "https://utopia-studio.co/design-system/motion-profiles.schema.json",
+  "version": 1,
+  "contract": {
+    "themeChooses": "motion personality and semantic recipes",
+    "applicationChooses": "runtime adapter",
+    "componentRequests": "feedback, page, surface, or layout",
+    "escapeHatch": "motion={false}",
+    "reducedMotion": "apply the semantic final state immediately without transform, filter, or temporal animation"
+  },
+  "adapters": [
+    { "id": "waapi", "package": "built-in", "entry": "Motion" },
+    { "id": "framer-motion", "package": "framer-motion", "entry": "MotionFramer" },
+    { "id": "animejs", "package": "animejs", "entry": "MotionAnime" },
+    { "id": "gsap", "package": "gsap", "entry": "MotionGsap" }
+  ],
+  "profiles": [
+    {
+      "id": "ceremonial",
+      "label": "Ceremonial reveal",
+      "themes": ["utopia-default"],
+      "personality": "ceremonial",
+      "description": "A composed, high-fidelity reveal with restrained blur and long deceleration.",
+      "rules": ["Keep direct feedback fast", "Use blur only for page and large-surface reveals", "Make exits shorter than entrances"],
+      "timings": {
+        "press": { "duration": 0.16, "ease": [0.2, 0, 0, 1] },
+        "page": { "duration": 0.42, "ease": [0.16, 1, 0.3, 1] },
+        "expand": { "duration": 0.36, "ease": [0.16, 1, 0.3, 1] },
+        "reveal": { "duration": 0.44, "ease": [0.16, 1, 0.3, 1] },
+        "icon": { "duration": 0.64, "ease": [0.16, 1, 0.3, 1] }
+      },
+      "recipes": {
+        "feedback": {
+          "enter": { "from": { "scale": 1 }, "to": { "scale": 0.98 }, "timing": { "duration": 0.14, "ease": [0.2, 0, 0, 1] } },
+          "exit": { "from": { "scale": 0.98 }, "to": { "scale": 1 }, "timing": { "duration": 0.12, "ease": [0.2, 0, 0, 1] } }
+        },
+        "page": {
+          "enter": { "from": { "opacity": 0, "y": 6, "blur": 8 }, "to": { "opacity": 1, "x": 0, "y": 0, "scale": 1, "rotate": 0, "blur": 0 }, "timing": { "duration": 0.42, "ease": [0.16, 1, 0.3, 1] } },
+          "exit": { "from": { "opacity": 1, "x": 0, "y": 0, "scale": 1, "rotate": 0, "blur": 0 }, "to": { "opacity": 0, "y": -2, "blur": 4 }, "timing": { "duration": 0.24, "ease": [0.7, 0, 0.84, 0] } }
+        },
+        "surface": {
+          "enter": { "from": { "opacity": 0, "y": 8, "scale": 0.995, "blur": 8 }, "to": { "opacity": 1, "x": 0, "y": 0, "scale": 1, "rotate": 0, "blur": 0 }, "timing": { "duration": 0.44, "ease": [0.16, 1, 0.3, 1] } },
+          "exit": { "from": { "opacity": 1, "x": 0, "y": 0, "scale": 1, "rotate": 0, "blur": 0 }, "to": { "opacity": 0, "y": 2, "scale": 0.995, "blur": 4 }, "timing": { "duration": 0.26, "ease": [0.7, 0, 0.84, 0] } }
+        },
+        "layout": {
+          "enter": { "from": { "opacity": 0.88, "x": 8 }, "to": { "opacity": 1, "x": 0, "y": 0, "scale": 1, "rotate": 0, "blur": 0 }, "timing": { "duration": 0.36, "ease": [0.16, 1, 0.3, 1] } },
+          "exit": { "from": { "opacity": 1, "x": 0, "y": 0, "scale": 1, "rotate": 0, "blur": 0 }, "to": { "opacity": 0.88, "x": 4 }, "timing": { "duration": 0.22, "ease": [0.7, 0, 0.84, 0] } }
+        }
+      },
+      "orchestration": { "delayChildren": 0.04, "stagger": 0.035 }
+    },
+    {
+      "id": "swift",
+      "label": "Swift response",
+      "themes": ["dextrum"],
+      "personality": "swift",
+      "description": "Fast, compact movement for dense technical workflows.",
+      "rules": ["No reveal blur", "No orchestration delay", "Prefer short directional shifts"],
+      "timings": {
+        "press": { "duration": 0.08, "ease": [0.2, 0, 0, 1] },
+        "page": { "duration": 0.14, "ease": [0.2, 0, 0, 1] },
+        "expand": { "duration": 0.16, "ease": [0.2, 0, 0, 1] },
+        "reveal": { "duration": 0.14, "ease": [0.2, 0, 0, 1] },
+        "icon": { "duration": 0.24, "ease": [0.2, 0, 0, 1] }
+      },
+      "recipes": {
+        "feedback": {
+          "enter": { "from": { "scale": 1 }, "to": { "scale": 0.97 }, "timing": { "duration": 0.08, "ease": [0.2, 0, 0, 1] } },
+          "exit": { "from": { "scale": 0.97 }, "to": { "scale": 1 }, "timing": { "duration": 0.07, "ease": [0.2, 0, 0, 1] } }
+        },
+        "page": {
+          "enter": { "from": { "opacity": 0, "x": 3 }, "to": { "opacity": 1, "x": 0, "y": 0, "scale": 1, "rotate": 0, "blur": 0 }, "timing": { "duration": 0.14, "ease": [0.2, 0, 0, 1] } },
+          "exit": { "from": { "opacity": 1, "x": 0, "y": 0, "scale": 1, "rotate": 0, "blur": 0 }, "to": { "opacity": 0, "x": -2 }, "timing": { "duration": 0.09, "ease": [0.7, 0, 0.84, 0] } }
+        },
+        "surface": {
+          "enter": { "from": { "opacity": 0, "y": 2 }, "to": { "opacity": 1, "x": 0, "y": 0, "scale": 1, "rotate": 0, "blur": 0 }, "timing": { "duration": 0.14, "ease": [0.2, 0, 0, 1] } },
+          "exit": { "from": { "opacity": 1, "x": 0, "y": 0, "scale": 1, "rotate": 0, "blur": 0 }, "to": { "opacity": 0 }, "timing": { "duration": 0.09, "ease": [0.7, 0, 0.84, 0] } }
+        },
+        "layout": {
+          "enter": { "from": { "opacity": 0.94, "x": 4 }, "to": { "opacity": 1, "x": 0, "y": 0, "scale": 1, "rotate": 0, "blur": 0 }, "timing": { "duration": 0.16, "ease": [0.2, 0, 0, 1] } },
+          "exit": { "from": { "opacity": 1, "x": 0, "y": 0, "scale": 1, "rotate": 0, "blur": 0 }, "to": { "opacity": 0.94, "x": 2 }, "timing": { "duration": 0.1, "ease": [0.7, 0, 0.84, 0] } }
+        }
+      },
+      "orchestration": { "delayChildren": 0, "stagger": 0 }
+    },
+    {
+      "id": "precise",
+      "label": "Precise dissolve",
+      "themes": ["barrier-intelligence"],
+      "personality": "precise",
+      "description": "Controlled dissolves and small scale changes for analytical surfaces.",
+      "rules": ["Prefer opacity over travel", "Keep scale changes below two percent", "Preserve analytical continuity"],
+      "timings": {
+        "press": { "duration": 0.1, "ease": [0.2, 0, 0, 1] },
+        "page": { "duration": 0.2, "ease": [0.16, 1, 0.3, 1] },
+        "expand": { "duration": 0.22, "ease": [0.16, 1, 0.3, 1] },
+        "reveal": { "duration": 0.24, "ease": [0.16, 1, 0.3, 1] },
+        "icon": { "duration": 0.32, "ease": [0.16, 1, 0.3, 1] }
+      },
+      "recipes": {
+        "feedback": {
+          "enter": { "from": { "scale": 1 }, "to": { "scale": 0.985 }, "timing": { "duration": 0.1, "ease": [0.2, 0, 0, 1] } },
+          "exit": { "from": { "scale": 0.985 }, "to": { "scale": 1 }, "timing": { "duration": 0.08, "ease": [0.2, 0, 0, 1] } }
+        },
+        "page": {
+          "enter": { "from": { "opacity": 0 }, "to": { "opacity": 1, "x": 0, "y": 0, "scale": 1, "rotate": 0, "blur": 0 }, "timing": { "duration": 0.2, "ease": [0.16, 1, 0.3, 1] } },
+          "exit": { "from": { "opacity": 1, "x": 0, "y": 0, "scale": 1, "rotate": 0, "blur": 0 }, "to": { "opacity": 0 }, "timing": { "duration": 0.14, "ease": [0.7, 0, 0.84, 0] } }
+        },
+        "surface": {
+          "enter": { "from": { "opacity": 0, "scale": 0.99 }, "to": { "opacity": 1, "x": 0, "y": 0, "scale": 1, "rotate": 0, "blur": 0 }, "timing": { "duration": 0.24, "ease": [0.16, 1, 0.3, 1] } },
+          "exit": { "from": { "opacity": 1, "x": 0, "y": 0, "scale": 1, "rotate": 0, "blur": 0 }, "to": { "opacity": 0, "scale": 0.995 }, "timing": { "duration": 0.16, "ease": [0.7, 0, 0.84, 0] } }
+        },
+        "layout": {
+          "enter": { "from": { "opacity": 0.92, "x": 5 }, "to": { "opacity": 1, "x": 0, "y": 0, "scale": 1, "rotate": 0, "blur": 0 }, "timing": { "duration": 0.22, "ease": [0.16, 1, 0.3, 1] } },
+          "exit": { "from": { "opacity": 1, "x": 0, "y": 0, "scale": 1, "rotate": 0, "blur": 0 }, "to": { "opacity": 0.92, "x": 3 }, "timing": { "duration": 0.14, "ease": [0.7, 0, 0.84, 0] } }
+        }
+      },
+      "orchestration": { "delayChildren": 0.02, "stagger": 0.02 }
+    }
+  ]
+}

package/data/manifests/theme-barrier-intelligence.json

@@ -9,6 +9,7 @@
     "packages/design-system/src/themes/barrier-intelligence.css",
     "packages/design-system/src/manifests/theme-barrier-intelligence.json"
   ],
+  "motionProfile": "precise",
   "brandPrimitives": {
     "colors": {
       "black": "#000000",
@@ -23,16 +24,22 @@
       "goldDark": "#8A6637",
       "gold": "#A6824C",
       "goldLight": "#D2AC6C",
-      "goldForeground": "#1A1208"
+      "goldForeground": "#1A1208",
+      "detectorLime": "#A6B86A",
+      "assuranceAtRisk": "#C47C48",
+      "assuranceLost": "#C76B62",
+      "assuranceWarning": "#D2A65A"
     },
     "typography": {
       "appWebsite": {
         "ui": "Hanken Grotesk",
+        "mono": "JetBrains Mono",
         "use": "Product UI, dashboards, documentation, and long-form reading"
       },
       "arabicFamily": "IBM Plex Sans Arabic",
       "weights": {
-        "hankenGrotesk": [400, 500, 600, 700]
+        "hankenGrotesk": [400, 500, 600, 700],
+        "jetBrainsMono": [400, 500, 600]
       },
       "arabicWeights": [400, 500, 700],
       "headlineCasing": "sentence",
@@ -66,7 +73,21 @@
     "--font-sans": "Hanken Grotesk",
     "--font-ui-support": "Hanken Grotesk",
     "--font-marketing-display": "Hanken Grotesk scoped through theme selectors",
+    "--font-mono": "JetBrains Mono",
     "--font-arabic": "IBM Plex Sans Arabic",
+    "--font-size-marketing-h1": "clamp(3rem, 6vw, 5.75rem)",
+    "--font-size-marketing-h2": "clamp(2.25rem, 4vw, 3.75rem)",
+    "--font-size-marketing-h3": "clamp(1.5rem, 2.5vw, 2.25rem)",
+    "--line-height-marketing-h1": "1",
+    "--line-height-marketing-h2": "1.06",
+    "--line-height-marketing-h3": "1.14",
+    "--measure-marketing-h1": "12ch",
+    "--measure-marketing-h2": "18ch",
+    "--measure-marketing-h3": "28ch",
+    "--container-standard": "72rem",
+    "--container-wide": "90rem",
+    "--page-gutter": "clamp(1rem, 3vw, 2.5rem)",
+    "--content-measure": "72ch",
     "--sidebar-width": "17rem",
     "--shadow-control": "none",
     "--control-height-sm": "2rem",
@@ -77,6 +98,48 @@
     "--modal-surface": "Card High",
     "--popover-surface": "Card High"
   },
+  "activationContract": {
+    "brandAttribute": "data-brand=\"barrier-intelligence\"",
+    "modeAttribute": "data-color-mode=\"dark|light|system\"",
+    "defaultMode": "dark",
+    "legacyAlias": "data-theme=\"barrier-intelligence\" remains supported during migration",
+    "rule": "Changing brand must not overwrite the persisted color mode. System follows prefers-color-scheme."
+  },
+  "layoutContract": {
+    "standard": "--container-standard",
+    "wide": "--container-wide",
+    "gutter": "--page-gutter",
+    "readingMeasure": "--content-measure",
+    "formula": "inline-size: min(calc(100% - 2 * var(--page-gutter)), var(--container-standard)); margin-inline: auto",
+    "rule": "Navigation, hero, and body content share the same responsive gutter. Products do not invent --page or --hero-page aliases."
+  },
+  "detectorStatus": {
+    "primitive": { "token": "--bi-detector-lime", "value": "#A6B86A" },
+    "semanticTokens": ["--detector-active", "--detector-active-foreground", "--detector-active-surface", "--detector-active-border"],
+    "use": ["active detectors", "verified detector output"],
+    "avoid": ["general calls to action", "decorative glow", "neon page accents"],
+    "accessibility": "Pair color with an icon and localized status label; verify text and control contrast in Dark and Light."
+  },
+  "assuranceStates": {
+    "credited": ["--assurance-credited", "--assurance-credited-foreground", "--assurance-credited-surface", "--assurance-credited-border"],
+    "atRisk": ["--assurance-at-risk", "--assurance-at-risk-foreground", "--assurance-at-risk-surface", "--assurance-at-risk-border"],
+    "lost": ["--assurance-lost", "--assurance-lost-foreground", "--assurance-lost-surface", "--assurance-lost-border"],
+    "warning": ["--assurance-warning", "--assurance-warning-foreground", "--assurance-warning-surface", "--assurance-warning-border"],
+    "verified": ["--assurance-verified", "--assurance-verified-foreground", "--assurance-verified-surface", "--assurance-verified-border"],
+    "rule": "Assurance states are domain semantics, not aliases for generic success/warning/destructive. Never communicate state by color alone."
+  },
+  "motionContract": {
+    "durations": ["--motion-duration-press", "--motion-duration-page", "--motion-duration-expand", "--motion-duration-reveal", "--motion-duration-icon"],
+    "easing": ["--motion-ease-standard", "--motion-ease-emphasized", "--motion-ease-icon"],
+    "distance": { "page": "6px", "reveal": "10px" },
+    "reducedMotion": "Core sets durations and distances to zero, disables icon animation, and restores press scale to 1 under prefers-reduced-motion."
+  },
+  "fontSupply": {
+    "hankenGrotesk": "Loaded by the theme stylesheet from Google Fonts",
+    "jetBrainsMono": "Loaded by the theme stylesheet from Google Fonts",
+    "ibmPlexSansArabic": "Self-hosted in the package with 400, 500, and 700 weights",
+    "display": "swap"
+  },
   "visualPolicy": {
     "tone": ["rigorous", "quiet", "technical", "premium"],
     "allow": [
@@ -84,14 +147,16 @@
       "warm gold accents for primary action and signal",
       "neutral ink hierarchy for reading",
       "rounded cards with hairline borders",
-      "minimal shadow; depth via border and surface steps"
+      "minimal shadow; depth via border and surface steps",
+      "restrained detector lime for active and verified engineering states"
     ],
     "avoid": [
       "bright neon accents",
       "colorful gradients as a default surface treatment",
       "overly rounded, playful geometry",
       "Utopia brick red palette",
-      "marketing display fonts in dense app UI"
+      "marketing display fonts in dense app UI",
+      "detector lime used as a decorative or glowing accent"
     ]
   },
   "iconPolicy": {
@@ -101,6 +166,15 @@
     "avoid": ["emoji", "mixed icon families in one surface"],
     "coreNote": "Icon policy is theme-owned. Core components remain icon-system neutral."
   },
+  "marketingAssetPolicy": {
+    "relationshipToIcons": "Lucide remains the UI icon system. Three-dimensional engineering assets are marketing media, not component icons.",
+    "palette": ["warm gold", "controlled grayscale", "restrained detector lime"],
+    "material": "Machined, technical, and restrained rather than glossy or toy-like.",
+    "lighting": "Directional studio lighting with clear form and no decorative neon glow.",
+    "background": "Near-black or controlled neutral fields with sufficient object separation.",
+    "use": ["engineering concepts", "detector visualization", "assurance evidence", "product capability storytelling"],
+    "avoid": ["generic abstract blobs", "glassmorphism", "cyberpunk glow", "decorative lime accents", "Lucide icons rendered as 3D objects"]
+  },
   "translations": {
     "ar": {
       "summary": "ثيم Barrier Intelligence مربوط بعقد Ceramic الدلالي. يستخدم أسطح منتجات شبه سوداء ولمسات ذهبية دافئة وتسلسلا محايدا محسوبا. يقود Hanken Grotesk واجهة المنتج والتوثيق، وتبقى أي طباعة تسويقية محصورة في محددات يملكها الثيم.",
@@ -114,9 +188,14 @@
   "aiRules": [
     "Read this theme policy after the core semantic contract.",
     "Map Barrier Intelligence palette through semantic tokens only.",
+    "Select the Barrier Intelligence brand with data-brand and select Dark, Light, or System independently with data-color-mode.",
+    "Use core container and gutter tokens instead of product-local --page or --hero-page aliases.",
     "Use gold for primary actions and high-signal emphasis, not as a full-page wash.",
+    "Use detector lime only for active detectors and verified states, always with a non-color status cue.",
+    "Use assurance semantic token families for credited, at risk, lost, warning, and verified states.",
     "Prefer near-black and stepped card surfaces with ink hierarchy.",
     "Use Hanken Grotesk for Latin app UI and body copy in this theme.",
+    "Use the dedicated marketing H1, H2, and H3 size, line-height, and measure tokens instead of scaling --font-size-display ad hoc.",
     "Keep Arabic on IBM Plex Sans Arabic tokens.",
     "Do not swap Ceramic shell navigation branding when this theme is active."
   ]