@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/development/frontend/ui-polish/cli/ui-polish/index.ts

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * ui-polish/index.ts — Entry point.
+ * parse args → validate → load tokens → dispatch to audit() or apply() → print JSON.
+ *
+ * Invoked by Claude via Bash. See sibling SKILL.md for the invocation contract.
+ */
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Command } from 'commander';
+import { validateArgs } from './validate.js';
+import { audit, loadTokens } from './audit.js';
+import { apply } from './apply.js';
+import type { UiPolishOutput, UiPolishMode } from './types.js';
+
+const program = new Command();
+
+program
+  .name('ui-polish')
+  .description('Audit / apply UI conformity fixes on a generated SmartStack web app')
+  .requiredOption('--project-path <path>', 'Absolute path to the generated web root (holds src/pages)')
+  .requiredOption('--mode <mode>', 'audit | apply', 'audit')
+  .option('--rules <list>', 'Comma-separated rule IDs to run (default = all)')
+  .option('--page <list>', 'Comma-separated page file path(s) relative to project root to scan (default = all pages)')
+  .option('--url <list>', 'Comma-separated URL paths to resolve to component files via PageRegistry')
+  .option('--tokens-file <path>', 'Override path for tokens.json')
+  .option('--regenerate-threshold <n>', 'Pages with ≥ N errors get rebuilt from template in apply mode (default 3, 0 = disable regen)', '3')
+  .parse(process.argv);
+
+const opts = program.opts();
+
+const raw = {
+  projectPath: opts.projectPath as string,
+  mode: opts.mode as UiPolishMode,
+  rules: typeof opts.rules === 'string'
+    ? opts.rules.split(',').map((s: string) => s.trim()).filter(Boolean)
+    : [],
+  paths: typeof opts.page === 'string'
+    ? opts.page.split(',').map((s: string) => s.trim()).filter(Boolean)
+    : [],
+  urls: typeof opts.url === 'string'
+    ? opts.url.split(',').map((s: string) => s.trim()).filter(Boolean)
+    : [],
+  tokensFile: opts.tokensFile as string | undefined,
+  regenerateThreshold: Number(opts.regenerateThreshold ?? 3),
+};
+
+const validation = validateArgs(raw);
+if (!validation.valid || !validation.args) {
+  const output: UiPolishOutput = {
+    success: false,
+    command: 'ui-polish',
+    data: { mode: (raw.mode ?? 'audit'), rulesRun: [], valid: false },
+    report: null,
+    filesModified: [],
+    errors: validation.errors,
+    warnings: [],
+    nextSteps: [],
+  };
+  console.log(JSON.stringify(output, null, 2));
+  process.exit(1);
+}
+
+// Async work is wrapped in an IIFE (not top-level await) so tsx can run this
+// file in any module context — consistent with the other dev CLIs' `void main()`.
+void (async () => {
+  try {
+    // Default tokens.json is sibling of the skill folder.
+  const __dirname = path.dirname(fileURLToPath(import.meta.url));
+  const defaultTokens = path.resolve(__dirname, '../../tokens.json');
+  const tokensPath = validation.args.tokensFile ?? defaultTokens;
+  const tokens = await loadTokens(tokensPath);
+
+  const report = validation.args.mode === 'apply'
+    ? await apply(validation.args, tokens)
+    : await audit(validation.args, tokens);
+
+  const valid = report.counts.errors === 0;
+  const rulesRun = validation.args.rules.length > 0
+    ? validation.args.rules
+    : tokens.hardRules.map((r) => r.id);
+
+  const nextSteps: string[] = [];
+  if (report.counts.errors > 0) {
+    nextSteps.push(
+      `${report.counts.errors} ERROR finding${report.counts.errors > 1 ? 's' : ''} — blocking UI polish gate.`,
+    );
+    if (validation.args.mode === 'audit') {
+      const fixable = report.findings.filter((f) => f.autoFixable).length;
+      if (fixable > 0) {
+        nextSteps.push(`Run with --mode apply to auto-fix ${fixable} mechanical issue(s).`);
+      }
+    }
+  }
+  if (validation.args.mode === 'apply' && 'fixesApplied' in report) {
+    nextSteps.push(
+      `Applied ${report.fixesApplied} fix(es) across ${report.filesModified.length} file(s). Re-run --mode audit to verify.`,
+    );
+    if (report.fixesSkipped.length > 0) {
+      nextSteps.push(
+        `${report.fixesSkipped.length} finding(s) were auto-fixable in tokens.json but could not be rewritten mechanically (file parse issue or ambiguous context). Claude should handle those.`,
+      );
+    }
+  }
+
+  const output: UiPolishOutput = {
+    success: true,
+    command: 'ui-polish',
+    data: { mode: validation.args.mode, rulesRun, valid },
+    report,
+    filesModified: 'filesModified' in report ? report.filesModified : [],
+    errors: [],
+    warnings: [],
+    nextSteps,
+  };
+  console.log(JSON.stringify(output, null, 2));
+  process.exit(valid ? 0 : 1);
+} catch (err) {
+  const message = err instanceof Error ? err.message : String(err);
+  const output: UiPolishOutput = {
+    success: false,
+    command: 'ui-polish',
+    data: { mode: validation.args.mode, rulesRun: [], valid: false },
+    report: null,
+    filesModified: [],
+    errors: [`Unexpected error: ${message}`],
+    warnings: [],
+    nextSteps: [],
+  };
+  console.log(JSON.stringify(output, null, 2));
+  process.exit(1);
+  }
+})();

package/templates/skills/development/frontend/ui-polish/cli/ui-polish/types.ts

@@ -0,0 +1,121 @@
+/**
+ * ui-polish/types.ts — CLI args + finding + report shape for the UI audit
+ * of a generated SmartStack web application.
+ *
+ * Source of truth for the rule catalogue is the sibling tokens.json — this
+ * file only mirrors its shape as TypeScript types so audit.ts and apply.ts
+ * can type-check the rule data they load at runtime.
+ */
+import { z } from 'zod';
+
+export const UiPolishModeSchema = z.enum(['audit', 'apply']);
+export type UiPolishMode = z.infer<typeof UiPolishModeSchema>;
+
+export const UiPolishArgsSchema = z.object({
+  /** Absolute path to the generated SmartStack web root (holds src/pages). */
+  projectPath: z.string().min(1),
+  /** `audit` = report only ; `apply` = mechanical rewrite of fixable findings. */
+  mode: UiPolishModeSchema,
+  /** Subset of rule IDs to run (e.g. `['R1', 'R3']`). Empty = all. */
+  rules: z.array(z.string()).default([]),
+  /**
+   * Restrict the scan to these page file paths (relative to projectPath, or
+   * absolute). Empty = discover every page under src/pages + src/features.
+   * Lets the caller verify a single page (`--page src/pages/x/FooListPage.tsx`).
+   */
+  paths: z.array(z.string()).default([]),
+  /**
+   * URL paths (e.g. /administration/tenants/{id}) to resolve to component files
+   * via PageRegistry.register() data in src/extensions/*Registry.ts.
+   */
+  urls: z.array(z.string()).default([]),
+  /** Override path for tokens.json (defaults to skill-local copy). */
+  tokensFile: z.string().optional(),
+  /**
+   * Regeneration threshold — in `apply` mode, any *Page.tsx file with ≥ this
+   * many ERROR findings remaining after mechanical fixes is REBUILT from the
+   * scaffold-component template (OVERWRITES the existing content). Default 3.
+   * Set to 0 to disable regeneration and fall back to pure mechanical fixes.
+   * Set to 1 to regenerate aggressively on any remaining error.
+   */
+  regenerateThreshold: z.number().int().min(0).max(100).default(3),
+});
+
+export type UiPolishArgs = z.infer<typeof UiPolishArgsSchema>;
+
+// ─── Tokens JSON mirrors ──────────────────────────────────────────────────
+
+export type Severity = 'error' | 'warning' | 'info';
+
+export interface HardRule {
+  id: string;
+  description: string;
+  violation: string;
+  autoFixable: boolean;
+  severity: Severity;
+}
+
+export interface TokensFile {
+  version: string;
+  sourceFile: string;
+  extractedAt: string;
+  hardRules: HardRule[];
+  cssVariables: Record<string, unknown>;
+  componentClasses: Record<string, { class: string; description?: string }>;
+  sharedComponents: Record<string, unknown>;
+  extensionPattern: Record<string, unknown>;
+  importMap: Record<string, string>;
+}
+
+// ─── Audit report ─────────────────────────────────────────────────────────
+
+export interface Finding {
+  ruleId: string;
+  severity: Severity;
+  file: string;
+  line?: number;
+  message: string;
+  autoFixable: boolean;
+  /** Raw source snippet around the violation (for apply.ts to locate). */
+  snippet?: string;
+}
+
+export interface AuditReport {
+  projectPath: string;
+  filesInspected: number;
+  findings: Finding[];
+  counts: {
+    errors: number;
+    warnings: number;
+    infos: number;
+  };
+  byRule: Record<string, number>;
+}
+
+export interface ApplyReport extends AuditReport {
+  /** Findings actually rewritten by apply.ts. */
+  fixesApplied: number;
+  /** Paths of files rewritten. */
+  filesModified: string[];
+  /** Findings that were auto-fixable but couldn't be rewritten (e.g. file parse error). */
+  fixesSkipped: Finding[];
+  /** Per-file regeneration verdicts emitted by the Phase 3 regen pass. */
+  regenerations?: Array<{ file: string; regenerated: boolean; reason: string }>;
+}
+
+// ─── Output envelope ──────────────────────────────────────────────────────
+
+export interface UiPolishOutput {
+  success: boolean;
+  command: 'ui-polish';
+  data: {
+    mode: UiPolishMode;
+    rulesRun: string[];
+    valid: boolean;
+  };
+  report: AuditReport | ApplyReport | null;
+  filesModified: string[];
+  errors: string[];
+  warnings: string[];
+  nextSteps: string[];
+}

package/templates/skills/development/frontend/ui-polish/cli/ui-polish/validate.ts

@@ -0,0 +1,73 @@
+/**
+ * ui-polish/validate.ts — Args validation (Zod + projectPath sanity check).
+ * No file I/O beyond verifying projectPath exists and looks like a web root.
+ */
+import { existsSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { UiPolishArgsSchema, type UiPolishArgs } from './types.js';
+
+export interface ArgsValidationResult {
+  valid: boolean;
+  args: UiPolishArgs | null;
+  errors: string[];
+}
+
+export function validateArgs(raw: unknown): ArgsValidationResult {
+  const parsed = UiPolishArgsSchema.safeParse(raw);
+  if (!parsed.success) {
+    return {
+      valid: false,
+      args: null,
+      errors: parsed.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`),
+    };
+  }
+
+  const args = parsed.data;
+  const errors: string[] = [];
+
+  // projectPath must exist and contain a `src` directory — refuse to scan arbitrary folders.
+  const abs = path.resolve(args.projectPath);
+  if (!existsSync(abs)) {
+    errors.push(`projectPath does not exist: ${abs}`);
+  } else if (!statSync(abs).isDirectory()) {
+    errors.push(`projectPath is not a directory: ${abs}`);
+  } else if (!existsSync(path.join(abs, 'src'))) {
+    errors.push(`projectPath has no "src" folder — are you sure this is a React app root? ${abs}`);
+  }
+
+  // rules must look like Rxx tags (free-form allowed but we at least warn on obvious garbage).
+  for (const ruleId of args.rules) {
+    if (!/^R\d+(-[a-z0-9-]+)?$/.test(ruleId)) {
+      errors.push(`rule id "${ruleId}" does not match /^R\\d+(-[a-z-]+)?$/ — expected e.g. "R1" or "R1-pagetemplate"`);
+    }
+  }
+
+  // tokensFile, if provided, must exist.
+  if (args.tokensFile) {
+    const tokensAbs = path.resolve(args.tokensFile);
+    if (!existsSync(tokensAbs)) {
+      errors.push(`tokensFile does not exist: ${tokensAbs}`);
+    }
+  }
+
+  // --url paths must look like URL paths (start with /).
+  for (const u of args.urls) {
+    if (!u.startsWith('/')) {
+      errors.push(`--url path must start with /: ${u}`);
+    }
+  }
+
+  // --page paths, if provided, must each exist, be a .tsx file, and live under projectPath.
+  for (const p of args.paths) {
+    const pageAbs = path.isAbsolute(p) ? p : path.join(abs, p);
+    if (!existsSync(pageAbs)) {
+      errors.push(`--page path does not exist: ${pageAbs}`);
+    } else if (!statSync(pageAbs).isFile() || !pageAbs.endsWith('.tsx')) {
+      errors.push(`--page path is not a .tsx file: ${pageAbs}`);
+    } else if (!path.resolve(pageAbs).startsWith(path.resolve(abs))) {
+      errors.push(`--page path is outside the project root: ${pageAbs}`);
+    }
+  }
+
+  return { valid: errors.length === 0, args, errors };
+}

package/templates/skills/development/frontend/ui-polish/tokens.json

@@ -0,0 +1,292 @@
+{
+  "$schema": "./tokens.schema.json",
+  "version": "1.3.0",
+  "sourceFile": "D:/01 - projets/SmartStack.app/features/customisation-ui/web/smartstack-web/src/base.css",
+  "extractedAt": "2026-04-22",
+  "description": "Design tokens + component classes + hard rules extracted verbatim from SmartStack.app customisation-ui. Source of truth for ui-polish audit.",
+
+  "cssVariables": {
+    "radius": {
+      "card": "12px",
+      "button": "8px",
+      "badge": "8px",
+      "input": "8px",
+      "modal": "16px",
+      "menuItem": "8px"
+    },
+    "colorPrimary": {
+      "50": "#eef2ff", "100": "#e0e7ff", "200": "#c7d2fe", "300": "#a5b4fc",
+      "400": "#818cf8", "500": "#6366f1", "600": "#4f46e5", "700": "#4338ca",
+      "800": "#3730a3", "900": "#312e81", "950": "#1e1b4b"
+    },
+    "colorAccent": {
+      "50": "#f5f3ff", "100": "#ede9fe", "200": "#ddd6fe", "300": "#c4b5fd",
+      "400": "#a78bfa", "500": "#8b5cf6", "600": "#7c3aed", "700": "#6d28d9",
+      "800": "#5b21b6", "900": "#4c1d95", "950": "#2e1065"
+    },
+    "backgrounds": {
+      "light": {
+        "bgApp": "#fafafa", "bgPrimary": "#ffffff", "bgSecondary": "#f4f4f5",
+        "bgTertiary": "#e4e4e7", "bgCard": "#ffffff", "bgHover": "#f4f4f5", "bgActive": "#e4e4e7"
+      },
+      "dark": {
+        "bgApp": "#161618", "bgPrimary": "#1c1c1f", "bgSecondary": "#232326",
+        "bgTertiary": "#2a2a2e", "bgCard": "#1c1c1f", "bgHover": "#27272a", "bgActive": "#3f3f46"
+      }
+    },
+    "text": {
+      "light": {
+        "textPrimary": "#18181b", "textSecondary": "#52525b",
+        "textTertiary": "#71717a", "textMuted": "#a1a1aa", "textInverse": "#fafafa"
+      },
+      "dark": {
+        "textPrimary": "#e4e4e7", "textSecondary": "#a1a1aa",
+        "textTertiary": "#71717a", "textMuted": "#52525b", "textInverse": "#e4e4e7"
+      }
+    },
+    "borders": {
+      "light": { "borderColor": "#e4e4e7", "borderSubtle": "#f4f4f5", "borderStrong": "#d4d4d8" },
+      "dark":  { "borderColor": "#3f3f46", "borderSubtle": "#27272a", "borderStrong": "#52525b" }
+    },
+    "status": {
+      "success": { "bg": "#f0fdfa", "text": "#0f766e", "border": "#99f6e4", "dot": "#14b8a6" },
+      "warning": { "bg": "#fffbeb", "text": "#b45309", "border": "#fde68a", "dot": "#f59e0b" },
+      "error":   { "bg": "#fff1f2", "text": "#be123c", "border": "#fecdd3", "dot": "#f43f5e" },
+      "info":    { "bg": "#f0f9ff", "text": "#0369a1", "border": "#bae6fd", "dot": "#0ea5e9" }
+    },
+    "fontSans": "'Inter', system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif"
+  },
+
+  "componentClasses": {
+    "card": { "description": "Surface card, solid background, shadow-sm", "class": ".card" },
+    "cardElevated": { "description": "Elevated card with shadow-md", "class": ".card-elevated" },
+    "btn": { "description": "Base button, radius-button, inline-flex, 0.5rem 1rem padding", "class": ".btn" },
+    "btnPrimary": { "description": "Primary CTA — accent-600 bg, white text", "class": ".btn .btn-primary" },
+    "btnSecondary": { "description": "Secondary — bg-secondary, text-primary, border", "class": ".btn .btn-secondary" },
+    "btnSm": { "description": "Smaller padding variant", "class": ".btn .btn-sm" },
+    "btnGhost": { "description": "Transparent bg, hover bg-hover", "class": ".btn .btn-ghost" },
+    "input": { "description": "Form input, radius-input, focus ring accent-500", "class": ".input" },
+    "focusRing": { "description": "Accessibility focus ring — 3px accent-border box-shadow", "class": ".focus-ring" },
+    "badgeSuccess": { "class": ".badge-success" },
+    "badgeWarning": { "class": ".badge-warning" },
+    "badgeError":   { "class": ".badge-error" },
+    "badgeInfo":    { "class": ".badge-info" },
+    "badgeAccent":  { "class": ".badge-accent" },
+    "hoverCard":    { "description": "Translate -2px + shadow-lg on hover", "class": ".hover-card" },
+    "itemLight":    { "class": ".item-light" },
+    "itemMedium":   { "class": ".item-medium" },
+    "itemDark":     { "class": ".item-dark" },
+    "itemBorder":   { "class": ".item-border" },
+    "glass":        { "description": "Backdrop blur 10px + transparent bg", "class": ".glass" },
+    "gradientText": { "description": "135deg gradient primary→accent, -webkit-background-clip: text", "class": ".gradient-text" },
+    "animatedGradient": { "class": ".animated-gradient" },
+    "tooltipAnimation": { "class": ".tooltip-animation" }
+  },
+
+  "sharedComponents": {
+    "PageTemplate": {
+      "importFrom": "@/components/ui/PageTemplate",
+      "props": {
+        "title": { "type": "string", "required": true },
+        "subtitle": { "type": "string | null", "required": false },
+        "icon": { "type": "ReactNode (lucide-react icon)", "required": false },
+        "actions": { "type": "ReactNode (buttons)", "required": false },
+        "breadcrumbs": { "type": "BreadcrumbItem[]", "required": false },
+        "children": { "type": "ReactNode", "required": true },
+        "contentClassName": { "type": "string", "default": "space-y-6" }
+      },
+      "rule": "Every page MUST wrap its content in <PageTemplate>. No bare <div> or <main> at the page root."
+    },
+    "PageHeader": {
+      "importFrom": "@/components/ui/PageHeader",
+      "note": "Used internally by PageTemplate. Pages should NOT use PageHeader directly."
+    },
+    "DataTable": {
+      "importFrom": "@/components/ui/DataTable",
+      "props": ["data", "columns", "loading", "searchable", "searchPlaceholder", "pagination", "onRowClick", "getRowKey", "emptyMessage", "emptyIcon", "headerActions", "striped", "compact", "selectable", "selectedKeys", "onSelectionChange", "searchFilter", "defaultSortKey", "defaultSortDirection"],
+      "rule": "List views of entities MUST use DataTable, not raw <table>. Exception: list pages with complex nested sections (like PresetsListPage grouping by theme) may use raw <table> INSIDE a .card section for each group."
+    },
+    "EntityCard": {
+      "importFrom": "@/components/ui/EntityCard",
+      "props": ["avatar", "title", "subtitle", "description", "stats", "badge", "links", "actions", "tags", "onClick", "customHeader", "customBody", "customFooter"],
+      "rule": "Grid-of-cards views (dashboards, gallery lists) use EntityCard."
+    },
+    "Loader2": {
+      "importFrom": "lucide-react",
+      "rule": "Loading indicator MUST be Loader2 with animate-spin. No custom spinners."
+    }
+  },
+
+  "extensionPattern": {
+    "slotsPerEntity": [
+      "{entity}.header.actions",
+      "{entity}.table.columns.before",
+      "{entity}.table.columns.after",
+      "{entity}.form.fields.before",
+      "{entity}.form.fields.after",
+      "{entity}.card.content",
+      "{entity}.detail.header",
+      "{entity}.detail.sidebar"
+    ],
+    "hooks": ["onPageLoad", "onBeforeSave", "onAfterSave", "onFormSubmit"],
+    "source": "D:/01 - projets/SmartStack.app/features/customisation-ui/web/smartstack-web/src/extensions/README.md"
+  },
+
+  "hardRules": [
+    {
+      "id": "R1-pagetemplate",
+      "description": "Every page MUST wrap its content in <PageTemplate> from @/components/ui/PageTemplate.",
+      "violation": "Page returns bare <div> or <main> at the root instead of <PageTemplate>.",
+      "autoFixable": true,
+      "severity": "error"
+    },
+    {
+      "id": "R2-no-hex-colors",
+      "description": "Color values in className MUST use var(--token-name) syntax. Inline style='background: #xxxxxx' is allowed only for dynamically computed accent shades.",
+      "violation": "Hex hex values in className attributes (e.g. className=\"bg-[#6366f1]\"). Only var(--…) allowed.",
+      "autoFixable": false,
+      "severity": "warning"
+    },
+    {
+      "id": "R3-primary-cta",
+      "description": "Primary CTA button MUST use bg-[var(--color-accent-500)] or bg-[var(--color-accent-600)] with text-white, rounded-[var(--radius-button)]. Alternatively .btn .btn-primary helper class.",
+      "violation": "Primary action uses arbitrary color like bg-blue-500 or bg-[#6366f1].",
+      "autoFixable": true,
+      "severity": "error"
+    },
+    {
+      "id": "R4-i18n-namespace",
+      "description": "All user-facing text MUST flow through useTranslation('<module|entity>'). No hardcoded strings in JSX.",
+      "violation": "JSX contains hardcoded string literal (matched by /<[A-Z][a-zA-Z]+[^>]*>[^<{]+[a-z]/ heuristic).",
+      "autoFixable": false,
+      "severity": "error"
+    },
+    {
+      "id": "R5-lucide-icons",
+      "description": "Icons MUST be imported from lucide-react. No svg fragments, no heroicons, no custom icon packs.",
+      "violation": "Import from @heroicons, react-icons, or raw <svg> in JSX.",
+      "autoFixable": false,
+      "severity": "warning"
+    },
+    {
+      "id": "R6-loader2-spinner",
+      "description": "Loading state MUST render <Loader2 className=\"animate-spin\" /> from lucide-react. No custom spinner components.",
+      "violation": "Uses a non-Loader2 spinner or CSS-only spinner instead.",
+      "autoFixable": false,
+      "severity": "warning"
+    },
+    {
+      "id": "R7-error-banner-anatomy",
+      "description": "Error banners MUST use bg-[var(--error-bg)] border border-[var(--error-border)] text-[var(--error-text)] rounded-[var(--radius-card)]. No Tailwind red-* utilities.",
+      "violation": "Error banner uses bg-red-*, text-red-*, border-red-* utilities directly.",
+      "autoFixable": true,
+      "severity": "error"
+    },
+    {
+      "id": "R8-datatable-for-lists",
+      "description": "List views SHOULD use <DataTable> from @/components/ui/DataTable instead of raw <table>. Exception: nested tables inside .card sections (grouped lists like PresetsListPage).",
+      "violation": "A list view renders <table> at the top level when a flat list could use <DataTable>.",
+      "autoFixable": false,
+      "severity": "info"
+    },
+    {
+      "id": "R9-useparams-nullcheck",
+      "description": "useParams<{ id: string }>() result MUST be null-checked. If id is missing, navigate back to the parent list route.",
+      "violation": "const { id } = useParams(); api.get(`/x/${id}`); — missing !id guard + navigate.",
+      "autoFixable": false,
+      "severity": "error"
+    },
+    {
+      "id": "R10-permission-key-format",
+      "description": "PermissionGuard keys use format {module}.{section}.{action} (read/create/update/delete). NO appCode prefix.",
+      "violation": "permission=\"myapp.hrm.employees.read\" (appCode prefix forbidden) or permission=\"hrm_employees_read\" (underscores forbidden).",
+      "autoFixable": true,
+      "severity": "error"
+    },
+    {
+      "id": "R11-slot-anatomy",
+      "description": "Pages SHOULD expose Slot/Fill injection points: {entity}.header.actions, {entity}.table.columns.before/after, {entity}.form.fields.before/after, {entity}.detail.header/sidebar, {entity}.card.content.",
+      "violation": "Generated page does not import Slot from @atlashub/smartstack or does not render any slot.",
+      "autoFixable": true,
+      "severity": "info"
+    },
+    {
+      "id": "R12-darktheme-base",
+      "description": "Dark theme MUST reference var(--bg-app) which resolves to #161618, NOT #0a0a0a or pure black. This is a design-system hard rule.",
+      "violation": "Inline dark mode color #000000 or #0a0a0a.",
+      "autoFixable": false,
+      "severity": "warning"
+    },
+    {
+      "id": "R13-badge-anatomy",
+      "description": "Status badges use inline-flex items-center gap-1 px-2 py-0.5 text-[10px] font-medium uppercase tracking-wider rounded bg-[var(--<status>-bg)] text-[var(--<status>-text)] border border-[var(--<status>-border)]. Or the .badge-<status> helper class.",
+      "violation": "Status badge uses bg-green-500 text-white or similar Tailwind arbitrary colors.",
+      "autoFixable": true,
+      "severity": "warning"
+    },
+    {
+      "id": "R14-no-hardcoded-colors",
+      "description": "Saturated/semantic colors MUST use design tokens — anywhere in className, not only buttons/badges/banners. Every Tailwind brand/status color utility (red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose) on any prefix (bg, text, border, ring, fill, stroke, outline, divide, decoration, placeholder, caret, accent, from, via, to) must map to var(--<status>-bg|text|border) or var(--color-accent-<shade>). This is the general net that complements the context-specific R3/R7/R13.",
+      "violation": "className contains a saturated Tailwind color utility, e.g. text-blue-600, bg-emerald-500, border-rose-400, ring-indigo-500.",
+      "autoFixable": true,
+      "severity": "error"
+    },
+    {
+      "id": "R15-no-neutral-hardcoded-colors",
+      "description": "Neutral colors SHOULD use theme surface tokens. Tailwind neutral families (slate, gray, zinc, neutral, stone) plus white/black are tokenised only for SURFACES (var(--bg-app|card|muted)) — bg-* utilities are auto-fixed. Neutral text/border have NO token in the current theme: they are reported for manual review (tokenise them in scaffold-theme, or accept them as idiomatic neutrals).",
+      "violation": "className contains a neutral Tailwind color utility, e.g. text-gray-500, bg-slate-100, border-zinc-200, bg-white, text-black.",
+      "autoFixable": true,
+      "severity": "warning"
+    },
+    {
+      "id": "R16-token-role-misuse",
+      "description": "Status tokens carry fixed roles: --<status>-bg is a PALE surface, --<status>-text is a SATURATED foreground, --<status>-border is a mid tint, --<status>-dot is a saturated indicator. Each must be used in its role. A -text token used as a background (bg-[var(--<status>-text)]) is illegible — content disappears, especially in dark mode; a -bg token used as text (text-[var(--<status>-bg)]) is invisible. The fix flips the misused token back to its role. When the element is a badge or banner, complete the soft triplet bg-[var(--<status>-bg)] text-[var(--<status>-text)] border-[var(--<status>-border)] manually. This catches a class of bug that R14 cannot — the colour is already a var(--token), so it is neither a hex (R2) nor a Tailwind family (R14): the token is simply bound to the wrong utility.",
+      "violation": "A status token is bound to the wrong utility prefix: bg-[var(--<status>-text)] (saturated text colour used as a fill) or text-[var(--<status>-bg)] (pale surface colour used as text).",
+      "autoFixable": true,
+      "severity": "error"
+    },
+    {
+      "id": "R17-status-token-as-decoration",
+      "description": "Status tokens (--success, --warning, --error, --info) carry FIXED MEANING — ok / caution / bad / neutral-info. They must signal real status, never serve as a decorative or categorical palette. Misuse is semantic, not mechanical: the value is already a var(--token) bound to the correct utility, so R2 (hex), R14 (Tailwind family) and R16 (utility role) all stay silent. The tell-tale is a color map whose decorative keys (blue, green, yellow, purple, …) are aliased to status tokens — e.g. const colorClasses = { blue: 'bg-[var(--info-bg)]', green: 'bg-[var(--success-bg)]', yellow: 'bg-[var(--warning-bg)]' } used to colour neutral metric/stat cards. A count of tenants rendered with --warning reads as an alert; a count rendered with --success implies success. Fix by reserving status tokens for real status (an active/inactive badge, a validation banner) and colouring decorative categories with var(--color-accent-<shade>) or a neutral surface (var(--bg-secondary)) instead. Not auto-fixable: choosing the right decorative token per category is a semantic decision the engine cannot make. Decorative keys mapped to var(--color-accent-*) or var(--bg-*) are correct and NOT flagged.",
+      "violation": "A decorative/categorical color-name key (blue, green, yellow, purple, …) is mapped to a status token value containing var(--<success|warning|error|info>-…), i.e. a status token used purely for its hue on non-status content.",
+      "autoFixable": false,
+      "severity": "warning"
+    },
+    {
+      "id": "R18-colors-outside-classname",
+      "description": "Tailwind color utilities appearing in JS data structures (string literals, object values, array elements) outside className attributes indicate hardcoded colors that escape the className-scoped R14/R15 scanners. These typically appear in config objects, option arrays, or conditional maps like { selectedBorder: 'border-gray-500' } and render with a hardcoded color even though no className violation fires.",
+      "violation": "A string literal outside any className attribute contains a Tailwind color utility (bg-blue-500, text-red-300, border-gray-200, etc.).",
+      "autoFixable": false,
+      "severity": "warning"
+    },
+    {
+      "id": "R19-hex-in-inline-style",
+      "description": "Hex colors (#xxx, #xxxxxx), rgb(), or rgba() values in inline style={{ }} props bypass the design token system entirely. These colors cannot respond to theme changes or dark mode toggling. Use CSS variable tokens via className (bg-[var(--token)]) or import the token value from the theme for dynamic styling.",
+      "violation": "An inline style={{ }} prop contains a hex color (#xxx/#xxxxxx), rgb() or rgba() value bound to a color CSS property (backgroundColor, color, borderColor, fill, stroke).",
+      "autoFixable": false,
+      "severity": "warning"
+    },
+    {
+      "id": "R20-accent-overuse",
+      "description": "Accent tokens used on non-CTA elements (cards, sections, headers) create visual noise — every surface competes for attention and nothing reads as the primary action. Patterns: (A) thick accent border (border-2+) on a card/container, (B) pale accent-50/100 as section/header background instead of var(--bg-secondary), (C) full accent fill (shade >= 500) on a non-button element. Reserve full accent for buttons/CTAs.",
+      "violation": "An accent token (var(--color-accent-*)) is used in a visually heavy way on a non-button element: thick border, section background, or full fill.",
+      "autoFixable": false,
+      "severity": "warning"
+    }
+  ],
+
+  "importMap": {
+    "PageTemplate": "@/components/ui/PageTemplate",
+    "DataTable": "@/components/ui/DataTable",
+    "EntityCard": "@/components/ui/EntityCard",
+    "ConfirmModal": "@/components/ui/ConfirmModal",
+    "Breadcrumb": "@/components/ui/Breadcrumb",
+    "Drawer": "@/components/ui/Drawer",
+    "Tooltip": "@/components/ui/Tooltip",
+    "icons": "lucide-react",
+    "i18n": "react-i18next",
+    "router": "react-router-dom",
+    "extensions": "@atlashub/smartstack",
+    "types": "@atlashub/smartstack"
+  }
+}