chore(ui-kit): enforce local boundary checks

Author: awesomestvi

.github/pull_request_template.md

@@ -6,9 +6,11 @@
 ## Review checklist
 
 - [ ] Shared UI was added to `src/app/components/primitives/` or `src/app/components/patterns/` when appropriate
+- [ ] If this adds shared UI, I can explain why it is not a primitive, pattern, or token when applicable
 - [ ] `src/app/components/shared/` was only used for app-specific shared UI or compatibility shims
 - [ ] Storybook stories were added or updated for shared UI changes
 - [ ] `pnpm check:stories` passes
+- [ ] `pnpm check:ui-kit` passes
 - [ ] Documentation was updated if Storybook taxonomy, component ownership, or UI system guidance changed
 - [ ] I tested responsive behavior where the UI changed
 - [ ] I tested relevant theme states where the UI changed

.github/workflows/ci.yml

@@ -34,6 +34,9 @@ jobs:
       - name: Validate Storybook standards
         run: pnpm check:stories
 
+      - name: Validate UI kit boundaries
+        run: pnpm check:ui-kit
+
       - name: Typecheck
         run: pnpm typecheck
 

.husky/pre-commit

@@ -1 +1 @@
-pnpm check:lockfile && pnpm check && pnpm check:stories && pnpm typecheck && pnpm test
+pnpm check:lockfile && pnpm check && pnpm check:stories && pnpm check:ui-kit && pnpm typecheck && pnpm test

design-system/README.md

@@ -8,6 +8,7 @@ shared UI layer backed by:
 
 - authoring in `src/app/components/primitives/` and `src/app/components/patterns/`
 - curated exports in `src/app/components/system/`
+- canonical developer imports in `src/app/ui-kit/`
 - shared visual decisions in theme/token helpers
 - Storybook as the review and documentation surface
 - component layers: `primitives/`, `patterns/`, `system/`, `shared/`, `layout/`, `ui/`, `figma/`
@@ -29,7 +30,7 @@ Use these docs when you are:
 2. Patterns over duplication. If the same structure appears across cards or dialogs, extract it.
 3. `system/` is a curated export layer, not the authoring location for new components.
 4. Performance matters. Visual richness cannot make the app unusable on wall panels or tablets.
-5. Storybook is the workshop. Stable shared UI should be reviewed there, not only in app pages.
+5. Storybook is the workshop and the internal UI-kit entrypoint. Stable shared UI should be reviewed there, not only in app pages.
 6. Unit tests cover logic seams. Shared utilities, store behavior, and controller logic should be
    verified in Vitest rather than only through visual review.
 

design-system/STORYBOOK_FOUNDATION.md

@@ -6,6 +6,7 @@ Navet should grow an internal component workshop before it grows a package works
 
 - Keep Navet in a single repo for now.
 - Build on an internal design-system layer under `src/app/components/system/`.
+- Treat Storybook as the official developer-facing UI-kit surface.
 - Run Storybook in this repo instead of splitting into a package workspace.
 - Delay a monorepo or package split until there is more than one real consumer.
 
@@ -57,10 +58,13 @@ The code foundation now groups stable exports into three buckets:
   - composed UI sections such as field wrappers, empty-state layouts, message bars, and preview cards
 - `src/app/components/system/`
   - curated public export surface for Storybook navigation and cross-app discovery
+- `src/app/ui-kit/`
+  - canonical developer import surface for Navet UI
 - `src/app/components/system/tokens/`
   - theme surface helpers, accent shell treatments, color helpers, and style calculators
 
 Author shared UI in `primitives/` or `patterns/` first. Re-export stable pieces through `system/`.
+For new usage and Storybook docs, prefer `@/app/ui-kit/*`.
 
 ## Story Hierarchy
 
@@ -102,6 +106,7 @@ Storybook sorting is controlled centrally in `.storybook/preview.tsx`. Avoid inv
 - Every story should render in all four themes where possible.
 - Every interactive component should show idle, hover, active, disabled, and selected states.
 - Every pattern should have mobile and desktop variants.
+- Every Storybook docs example should use `@/app/ui-kit/*` imports when a stable shared export exists.
 - Prefer real Navet copy and spacing tokens over synthetic examples.
 - Keep feature-specific data loaders and Home Assistant wiring out of stories.
 - Co-locate the story with the component or feature it documents.
@@ -116,4 +121,4 @@ Only move to a package workspace if one of these becomes true:
 - The UI system needs independent release/versioning
 - Build and ownership boundaries become painful in one package
 
-Until then, Storybook plus `src/app/components/system/` is the simpler path.
+Until then, Storybook plus `src/app/ui-kit/` is the simpler path.

package.json

@@ -17,8 +17,10 @@
     "format": "biome format --write ./src",
     "check": "biome check ./src",
     "check:stories": "node scripts/check-storybook-standards.mjs",
+    "check:ui-kit": "node scripts/check-ui-kit-boundaries.mjs",
     "check:lockfile": "node scripts/check-pnpm-lock-sync.mjs",
     "check:fix": "biome check --apply ./src",
+    "report:ui-kit": "node scripts/check-ui-kit-usage.mjs",
     "test": "vitest --config vitest.unit.config.ts --project unit",
     "test:coverage": "vitest --config vitest.unit.config.ts --project unit --coverage",
     "test:storybook": "vitest --project \"storybook:$PWD/.storybook\"",

scripts/check-ui-kit-boundaries.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+
+const ROOT = process.cwd();
+
+const SHARED_DIRS = [
+  'src/app/components/primitives',
+  'src/app/components/patterns',
+  'src/app/components/shared',
+  'src/app/components/system',
+  'src/app/ui-kit',
+];
+
+const PUBLIC_EXPORT_DIRS = ['src/app/components/system', 'src/app/ui-kit'];
+
+const LEGACY_MODAL_ALLOWLIST = new Set([
+  'src/app/features/security/components/camera-card/camera-settings-dialog.tsx',
+  'src/app/features/security/components/cover-card/view.tsx',
+  'src/app/features/climate/components/hvac-settings-dialog/index.tsx',
+  'src/app/features/weather/components/weather-card/weather-settings-dialog.tsx',
+  'src/app/features/lighting/components/light-card/light-settings-dialog.tsx',
+  'src/app/features/lighting/components/switch-settings-dialog.tsx',
+]);
+
+function walk(dir) {
+  const entries = fs.readdirSync(path.join(ROOT, dir), { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    const relativePath = path.join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      files.push(...walk(relativePath));
+      continue;
+    }
+
+    if (!entry.isFile()) {
+      continue;
+    }
+
+    if (!/\.(ts|tsx|js|jsx|mjs)$/.test(entry.name) || entry.name.includes('.stories.')) {
+      continue;
+    }
+
+    files.push(relativePath);
+  }
+
+  return files;
+}
+
+const violations = [];
+
+for (const dir of SHARED_DIRS) {
+  for (const relativePath of walk(dir)) {
+    const source = fs.readFileSync(path.join(ROOT, relativePath), 'utf8');
+
+    if (source.includes(`@/app/features/`)) {
+      violations.push(`${relativePath}: shared UI layers must not import from feature modules`);
+    }
+  }
+}
+
+for (const dir of PUBLIC_EXPORT_DIRS) {
+  for (const relativePath of walk(dir)) {
+    const source = fs.readFileSync(path.join(ROOT, relativePath), 'utf8');
+
+    if (/export\s+.*from\s+['"]@\/app\/features\//.test(source)) {
+      violations.push(`${relativePath}: public UI-kit surfaces must not re-export feature modules`);
+    }
+  }
+}
+
+for (const relativePath of [...walk('src/app/components/layout'), ...walk('src/app/features')]) {
+  const source = fs.readFileSync(path.join(ROOT, relativePath), 'utf8');
+
+  const hasLegacyModalRecipe =
+    /(fixed (left-1\/2 top-1\/2|top-1\/2 left-1\/2) z-50 .*shadow-2xl backdrop-blur-xl)/.test(
+      source
+    ) || /fixed inset-x-0 bottom-0 z-50 .*rounded-\[30px\].*shadow-2xl/.test(source);
+
+  if (hasLegacyModalRecipe && !LEGACY_MODAL_ALLOWLIST.has(relativePath)) {
+    violations.push(
+      `${relativePath}: use shared ModalSurface or SheetSurface instead of reauthoring shell recipes`
+    );
+  }
+}
+
+if (violations.length > 0) {
+  console.error('\nUI kit boundary check failed:\n');
+  for (const violation of violations) {
+    console.error(`- ${violation}`);
+  }
+  process.exit(1);
+}
+
+console.log('UI kit boundary check passed.');

scripts/check-ui-kit-usage.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+
+const ROOT = process.cwd();
+const APP_DIR = path.join(ROOT, 'src/app');
+
+function walk(dir) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+
+    if (entry.isDirectory()) {
+      files.push(...walk(fullPath));
+      continue;
+    }
+
+    if (!entry.isFile() || !/\.(ts|tsx)$/.test(entry.name) || entry.name.includes('.stories.')) {
+      continue;
+    }
+
+    files.push(fullPath);
+  }
+
+  return files;
+}
+
+const metrics = [];
+const featureLeakFiles = [];
+
+for (const fullPath of walk(APP_DIR)) {
+  const relativePath = path.relative(ROOT, fullPath);
+  const source = fs.readFileSync(fullPath, 'utf8');
+  const themeBranches = (source.match(/theme === '(light|glass|black|dark)'/g) ?? []).length;
+  const inlineStyles = (source.match(/style=\{\{/g) ?? []).length;
+  const arbitrarySurfaces =
+    (source.match(/rounded-\[[^\]]+\]/g) ?? []).length +
+    (source.match(/shadow-\[[^\]]+\]/g) ?? []).length +
+    (source.match(/bg-\[[^\]]+\]/g) ?? []).length +
+    (source.match(/border-\[[^\]]+\]/g) ?? []).length;
+
+  metrics.push({
+    relativePath,
+    themeBranches,
+    inlineStyles,
+    arbitrarySurfaces,
+  });
+
+  if (
+    /src\/app\/components\/(primitives|patterns|shared|system)\//.test(relativePath) &&
+    source.includes(`@/app/features/`)
+  ) {
+    featureLeakFiles.push(relativePath);
+  }
+}
+
+function printTop(title, key) {
+  console.log(`\n${title}`);
+  metrics
+    .filter((entry) => entry[key] > 0)
+    .sort((a, b) => b[key] - a[key])
+    .slice(0, 15)
+    .forEach((entry) => {
+      console.log(`- ${entry[key].toString().padStart(3, ' ')} ${entry.relativePath}`);
+    });
+}
+
+printTop('Top files by theme branching', 'themeBranches');
+printTop('Top files by inline style usage', 'inlineStyles');
+printTop('Top files by arbitrary surface classes', 'arbitrarySurfaces');
+
+console.log('\nShared-layer feature imports');
+if (featureLeakFiles.length === 0) {
+  console.log('- none');
+} else {
+  featureLeakFiles.sort().forEach((file) => console.log(`- ${file}`));
+}

src/app/components/README.md

@@ -18,6 +18,11 @@ This folder has three distinct roles:
   Do not treat `system/` as the source of truth for where new shared components are authored.
   `system/tokens` is the shared home for first-layer foundations such as spacing, radii, icon sizing, and focus behavior.
 
+- `ui-kit/`
+  Canonical import surface for Navet developers.
+  Prefer `@/app/ui-kit/primitives`, `@/app/ui-kit/patterns`, and `@/app/ui-kit/tokens`
+  in new docs, examples, and shared UI consumption. `system/` remains transitional.
+
 - `shared/`
   Existing app-specific shared components that do not belong in the primitive/pattern system.
   Temporary compatibility shims may appear here during migrations, but they should not be long-lived.
@@ -31,6 +36,7 @@ Guidelines:
 
 - Create new shared UI in `primitives/` or `patterns/` first.
 - Re-export stable shared pieces through `system/` once they are ready for broader use.
+- Prefer exposing and consuming stable shared UI through `ui-kit/`.
 - Before adding or widening primitives, align them to the existing foundation tokens in `src/app/components/system/tokens/`.
 - Treat any temporary compatibility shim in `shared/` as a migration path, not as the preferred import target.
 - Keep business logic and feature-specific state out of primitives.

src/app/components/layout/header-actions.tsx

@@ -55,13 +55,14 @@ export function HeaderMobileActions({
         hoverBg={hoverBg}
         isNotificationOpen={isNotificationOpen}
         mobileNotificationButtonRef={mobileNotificationButtonRef}
+        renderPanel
         setIsNotificationOpen={setIsNotificationOpen}
         textSecondary={textSecondary}
         unreadCount={unreadCount}
         mobile
       />
 
-      <UserDropdown avatarUrl={avatarUrl} />
+      <UserDropdown avatarUrl={avatarUrl} variant="mobile" />
     </div>
   );
 }
@@ -73,10 +74,13 @@ export function HeaderDesktopActions({
   hoverBg,
   isNotificationOpen,
   mobileNotificationButtonRef,
+  renderPanel = true,
   setIsNotificationOpen,
   textSecondary,
   unreadCount,
-}: Omit<HeaderActionsProps, 'isMobileSearchOpen' | 'onToggleMobileSearch' | 'searchAriaLabel'>) {
+}: Omit<HeaderActionsProps, 'isMobileSearchOpen' | 'onToggleMobileSearch' | 'searchAriaLabel'> & {
+  renderPanel?: boolean;
+}) {
   return (
     <>
       <HeaderNotificationButton
@@ -85,6 +89,7 @@ export function HeaderDesktopActions({
         hoverBg={hoverBg}
         isNotificationOpen={isNotificationOpen}
         mobileNotificationButtonRef={mobileNotificationButtonRef}
+        renderPanel={renderPanel}
         setIsNotificationOpen={setIsNotificationOpen}
         textSecondary={textSecondary}
         unreadCount={unreadCount}
@@ -94,13 +99,14 @@ export function HeaderDesktopActions({
   );
 }
 
-function HeaderNotificationButton({
+export function HeaderNotificationButton({
   activeColorValue,
   desktopNotificationButtonRef,
   hoverBg,
   isNotificationOpen,
   mobile = false,
   mobileNotificationButtonRef,
+  renderPanel = false,
   setIsNotificationOpen,
   textSecondary,
   unreadCount,
@@ -111,6 +117,7 @@ function HeaderNotificationButton({
   isNotificationOpen: boolean;
   mobile?: boolean;
   mobileNotificationButtonRef: RefObject<HTMLButtonElement | null>;
+  renderPanel?: boolean;
   setIsNotificationOpen: (open: boolean) => void;
   textSecondary: string;
   unreadCount: number;
@@ -140,7 +147,7 @@ function HeaderNotificationButton({
         ) : null}
       </button>
 
-      {!mobile ? (
+      {renderPanel ? (
         <NotificationPanel
           isOpen={isNotificationOpen}
           onClose={() => setIsNotificationOpen(false)}