@lucasvu/scope-ui 0.0.5 → 0.0.6

package/AI_SETUP.md

@@ -5,13 +5,19 @@ Mục tiêu của file này là để AI của project dùng `@lucasvu/scope-ui`
 Nếu project consumer đã cài package, cách nhanh nhất là chạy:
 
 ```bash
-npx scope-ui-init --list-themes
+npm install @lucasvu/scope-ui
 npx scope-ui-init --theme forest
 ```
 
-Nếu chưa cài `@lucasvu/scope-ui`, lệnh trên sẽ báo `E404` vì npm sẽ cố tải package tên `scope-ui-init`.
+Nếu chưa biết chọn preset nào thì chạy thêm:
+
+```bash
+npx scope-ui-init --list-themes
+```
+
+Nếu chưa cài `@lucasvu/scope-ui`, các lệnh trên sẽ báo `E404` vì npm sẽ cố tải package tên `scope-ui-init`.
 
-CLI này sẽ tạo `AGENTS.md` và `src/styles/ui-theme.css` theo đúng convention bên dưới. Nếu không truyền `--theme`, preset mặc định là `ocean`.
+CLI này sẽ tạo `AGENTS.md` và `src/styles/ui-theme.css` theo đúng convention bên dưới. `AGENTS.md` sẽ chứa luôn workflow step-by-step để agent dựng UI đúng thứ tự. Nếu không truyền `--theme`, preset mặc định là `ocean`.
 
 ## 1. Import style đúng thứ tự
 
@@ -67,8 +73,10 @@ Always:
 - import the project theme override file after the package stylesheet
 - use root exports from `@lucasvu/scope-ui`
 - stay inside the approved preset declared by `src/styles/ui-theme.css`
+- follow the step-by-step UI build workflow from `AGENTS.md` before writing JSX
+- fill the screen brief first: `routeUrl`, `sidebarItems`, `activeSidebarItemId`, `pageTitle`, `actions`, and the page-specific schema
 - read `uiAiManifest` to choose the right component by intent
-- read `uiThemeContract` before changing colors, surfaces, borders, or shadows
+- read `uiScreenBlueprint` and `uiThemeContract` before changing layout, colors, surfaces, borders, or shadows
 
 Do not:
 - import from `MainFe` unless the task explicitly targets a legacy screen
@@ -93,10 +101,11 @@ Component choice:
 Trong code, AI có thể đọc trực tiếp:
 
 ```ts
-import { uiAiManifest, uiThemeContract, uiThemePresets, uiProjectAiRules } from '@lucasvu/scope-ui'
+import { uiAiManifest, uiScreenBlueprint, uiThemeContract, uiThemePresets, uiProjectAiRules } from '@lucasvu/scope-ui'
 ```
 
 - `uiAiManifest`: chọn component theo intent
+- `uiScreenBlueprint`: brief input và khung layout chuẩn cho `list | form | detail | dashboard`
 - `uiThemeContract`: biết override token nào và override ở đâu
 - `uiThemePresets`: danh sách preset được duyệt để nhiều project dùng chung một visual language
 - `uiProjectAiRules`: rule ngắn gọn để inject vào agent của project

package/README.md

@@ -19,13 +19,19 @@ import '@lucasvu/scope-ui/styles.css';
 3. Nếu muốn bootstrap rule/theme cho AI trong project consumer:
 
 ```bash
-npx scope-ui-init --list-themes
+npm install @lucasvu/scope-ui
 npx scope-ui-init --theme sunset
 ```
 
-Lưu ý: lệnh này chỉ chạy được sau khi project đã cài `@lucasvu/scope-ui`. Nếu chưa cài package, `npx` sẽ đi tìm một package riêng tên `scope-ui-init` trên npm và báo `E404`.
+Nếu chưa biết chọn preset nào thì mới cần xem danh sách trước:
 
-Lệnh này sẽ tạo `AGENTS.md` và `src/styles/ui-theme.css` trong repo hiện tại theo preset đã chọn. Nếu không truyền `--theme`, preset mặc định là `ocean`. Dùng `--force` nếu muốn overwrite file đã tồn tại.
+```bash
+npx scope-ui-init --list-themes
+```
+
+Lưu ý: các lệnh này chỉ chạy được sau khi project đã cài `@lucasvu/scope-ui`. Nếu chưa cài package, `npx` sẽ đi tìm một package riêng tên `scope-ui-init` trên npm và báo `E404`.
+
+Lệnh này sẽ tạo `AGENTS.md` và `src/styles/ui-theme.css` trong repo hiện tại theo preset đã chọn. `AGENTS.md` giờ có thêm playbook step-by-step để agent dựng màn hình đúng layout/component/theme chung. Nếu không truyền `--theme`, preset mặc định là `ocean`. Dùng `--force` nếu muốn overwrite file đã tồn tại.
 
 4. Dùng component:
 
@@ -104,17 +110,21 @@ Nếu muốn AI render UI đúng và ổn định theo thư viện này, đừng
 
 - Import CSS global một lần: `@lucasvu/scope-ui/styles.css`
 - Import file theme override của project ngay sau package CSS, ví dụ `./styles/ui-theme.css`
+- Cài package trước khi bootstrap: `npm install @lucasvu/scope-ui`
 - Chạy `npx scope-ui-init --list-themes` để xem preset được duyệt
 - Chạy `npx scope-ui-init --theme <preset>` ở project consumer sau khi đã cài `@lucasvu/scope-ui` để tạo `AGENTS.md` và `src/styles/ui-theme.css`
 - Khoá project vào một preset thay vì tự bịa palette mới cho từng page
+- Để agent đọc luôn playbook trong `AGENTS.md` để đi đúng thứ tự: kiểm tra import, chọn component, dựng layout, rồi mới tinh chỉnh token
+- Buộc agent điền screen brief trước khi code: `routeUrl`, `sidebarItems`, `activeSidebarItemId`, `pageTitle`, `actions`, `filters`, `fields`, `tableColumns`
 - Chỉ dùng các component canonical ở root package; tránh `MainFe` nếu không phải legacy screen
 - Cho agent đọc `uiAiManifest` để biết component nào dùng cho intent nào, props quan trọng là gì, và khi nào không nên dùng
-- Cho agent đọc `uiThemeContract` và `uiThemePresets` để biết danh sách preset và token nào được phép override
+- Cho agent đọc `uiScreenBlueprint`, `uiThemeContract` và `uiThemePresets` để biết screen recipe, preset và token nào được phép override
 
 ```ts
 import {
   uiAiManifest,
   uiProjectAiRules,
+  uiScreenBlueprint,
   uiThemeContract,
   uiThemePresets,
 } from '@lucasvu/scope-ui';
@@ -122,6 +132,8 @@ import {
 
 `uiAiManifest` mô tả luật chọn component theo intent như: text input, textarea, fixed select, searchable select, async combobox, multi select, data table, alert, card và field wrapper.
 
+`uiScreenBlueprint` mô tả input brief bắt buộc cho từng màn hình như `routeUrl`, `sidebarItems`, `activeSidebarItemId`, `pageTitle`, `actions`, `filters`, `fields`, `tableColumns` và frame recipe cho `list | form | detail | dashboard`.
+
 `uiThemeContract` mô tả token màu, surface, border, shadow, radius, gradient và selector theme (`:root`, `.dark`, `[data-ui-theme='*']`) để AI không hardcode màu sai chỗ.
 
 `uiThemePresets` là danh sách preset được duyệt sẵn để nhiều project có thể chọn cùng một visual language mà không cần tự dựng theme từ đầu.
@@ -135,6 +147,7 @@ Nên để toàn bộ override theme của project vào một file riêng, ví d
 Cách nhanh nhất là generate file này từ preset:
 
 ```bash
+npm install @lucasvu/scope-ui
 npx scope-ui-init --list-themes
 npx scope-ui-init --theme ocean
 ```

package/bin/scope-ui-init.mjs

@@ -281,8 +281,12 @@ Usage:
   npx scope-ui-init
     Run this after @lucasvu/scope-ui has been installed in the consumer project.
 
-  npx scope-ui-init --list-themes
   npx scope-ui-init --theme sunset
+    Fast path when you already know the preset you want.
+
+  npx scope-ui-init --list-themes
+    Optional: inspect approved presets before choosing one.
+
   npx scope-ui-init --theme forest --force
   npx scope-ui-init --agents-file AGENTS.md --theme-file src/styles/ui-theme.css
 
@@ -338,12 +342,43 @@ This repo is locked to the \`${themePreset.label}\` theme preset (\`${themePrese
 Primary references:
 - \`node_modules/${PACKAGE_NAME}/README.md\`
 - \`node_modules/${PACKAGE_NAME}/AI_SETUP.md\`
+- \`uiScreenBlueprint\` and \`uiAiManifest\` from \`${PACKAGE_NAME}\`
 - \`${themeFile}\`
 
 Theme preset summary:
 - ${themePreset.description}
 - Recommended for: ${themePreset.recommendedFor.join(', ')}
 
+UI build workflow:
+1. Read \`${themeFile}\`, \`node_modules/${PACKAGE_NAME}/README.md\`, \`node_modules/${PACKAGE_NAME}/AI_SETUP.md\`, and the exported \`uiScreenBlueprint\` contract before generating UI.
+2. Fill the screen brief first. If route url, sidebar items, active sidebar item, title, actions, filters, fields, or columns are missing, ask for them or leave clear TODO placeholders instead of inventing them.
+3. Verify the app entry imports \`${PACKAGE_NAME}/styles.css\` first and the project theme file right after it.
+4. Identify the page kind (\`list | form | detail | dashboard\`), then map each block to canonical components from \`uiAiManifest\` before writing JSX.
+5. Build the shell in this order: \`Sidebar\` -> \`Breadcrumb\` -> \`PageTitle\` -> top actions -> page body cards/grids.
+6. For list pages, build filters first and then the \`DataTable\`. For form pages, build section cards and fields. For detail pages, build summary cards and related tables. For dashboard pages, build stat cards and then supporting tables/cards.
+7. Keep all colors, radius, surface, and shadow decisions inside \`${themeFile}\`. If the preset is insufficient, update tokens there instead of styling one page ad hoc.
+8. Before finishing, self-check: no \`MainFe\`, no hardcoded palette, correct import order, complete brief coverage, consistent spacing, and the screen still matches the shared preset.
+
+Screen brief template:
+- pageKind: list | form | detail | dashboard
+- routeUrl:
+- sidebarItems: [{ id, title, href }]
+- activeSidebarItemId:
+- breadcrumbs:
+- pageTitle:
+- pageSubtitle:
+- primaryAction:
+- secondaryActions:
+- summaryStats:
+- filters:
+- tableColumns:
+- rowActions:
+- formSections:
+- fields:
+- detailSections:
+- emptyState:
+- permissions:
+
 Always:
 - import \`${PACKAGE_NAME}/styles.css\` once at the app entry
 - import the project theme override file after the package stylesheet

package/dist/index.cjs

@@ -6647,6 +6647,7 @@ var uiAiManifest = {
   rules: [
     "Import the stylesheet once at the app entry before rendering any component.",
     "If the project declares an approved theme preset in AGENTS.md or ui-theme.css, stay inside that preset and do not invent a second palette.",
+    "Collect the screen brief first: route url, sidebar items, active sidebar item, page title, actions, and the page-specific content schema.",
     "Prefer the canonical component for each intent instead of mixing legacy MainFe components.",
     "Use Input/Textarea/Select label props directly for simple fields; use Field only to wrap custom controls or grouped content.",
     "Use Select for small fixed option lists, SearchableSelect for larger local lists, Combobox for type-and-pick flows, and AsyncCombobox for remote search.",
@@ -6862,6 +6863,213 @@ var uiAiManifest = {
   ]
 };
 
+// src/screen-blueprint.ts
+var uiScreenBriefFields = [
+  {
+    id: "pageKind",
+    label: "Page kind",
+    description: "Choose the base recipe for the screen.",
+    required: true,
+    appliesTo: ["all"],
+    example: "list"
+  },
+  {
+    id: "routeUrl",
+    label: "Route URL",
+    description: "Final route for the screen or feature entry.",
+    required: true,
+    appliesTo: ["all"],
+    example: "/admin/users"
+  },
+  {
+    id: "sidebarItems",
+    label: "Sidebar items",
+    description: "Sidebar entries with at least id, title, and href so the shell stays consistent.",
+    required: true,
+    appliesTo: ["all"],
+    example: '[{ id: "users", title: "Users", href: "/admin/users" }]'
+  },
+  {
+    id: "activeSidebarItemId",
+    label: "Active sidebar item id",
+    description: "The sidebar item that should appear active on this screen.",
+    required: true,
+    appliesTo: ["all"],
+    example: "users"
+  },
+  {
+    id: "breadcrumbs",
+    label: "Breadcrumbs",
+    description: "Ordered breadcrumb items for the page header.",
+    required: false,
+    appliesTo: ["all"],
+    example: '[{ label: "Admin", href: "/admin" }, { label: "Users", current: true }]'
+  },
+  {
+    id: "pageTitle",
+    label: "Page title",
+    description: "Main page heading shown in the content header.",
+    required: true,
+    appliesTo: ["all"],
+    example: "Users"
+  },
+  {
+    id: "pageSubtitle",
+    label: "Page subtitle",
+    description: "Short supporting text under the title.",
+    required: false,
+    appliesTo: ["all"],
+    example: "Manage internal user accounts and permissions."
+  },
+  {
+    id: "primaryAction",
+    label: "Primary action",
+    description: "The highest-emphasis action shown in the page header.",
+    required: false,
+    appliesTo: ["all"],
+    example: '{ label: "Create user", href: "/admin/users/create" }'
+  },
+  {
+    id: "secondaryActions",
+    label: "Secondary actions",
+    description: "Additional header actions such as export, refresh, or cancel.",
+    required: false,
+    appliesTo: ["all"],
+    example: '[{ label: "Export" }, { label: "Refresh" }]'
+  },
+  {
+    id: "summaryStats",
+    label: "Summary stats",
+    description: "Top-line numbers for dashboard or overview screens.",
+    required: false,
+    appliesTo: ["dashboard", "detail"],
+    example: '[{ label: "Active users", value: "1,204", trend: "up", delta: "+12%" }]'
+  },
+  {
+    id: "filters",
+    label: "Filters",
+    description: "Filter bar controls shown above list or dashboard content.",
+    required: false,
+    appliesTo: ["list", "dashboard"],
+    example: '[{ type: "search", label: "Search user" }, { type: "select", label: "Role" }]'
+  },
+  {
+    id: "tableColumns",
+    label: "Table columns",
+    description: "Columns for a list table, including label and render intent.",
+    required: false,
+    appliesTo: ["list", "detail", "dashboard"],
+    example: '[{ key: "name", title: "Name" }, { key: "role", title: "Role" }]'
+  },
+  {
+    id: "rowActions",
+    label: "Row actions",
+    description: "Per-row actions for table screens.",
+    required: false,
+    appliesTo: ["list", "detail"],
+    example: '[{ label: "Edit" }, { label: "Reset password" }]'
+  },
+  {
+    id: "formSections",
+    label: "Form sections",
+    description: "Grouped form sections and the fields inside each section.",
+    required: false,
+    appliesTo: ["form"],
+    example: '[{ title: "Basic info", fields: ["name", "email", "role"] }]'
+  },
+  {
+    id: "fields",
+    label: "Fields",
+    description: "Detailed field list with type, label, required state, and helper text.",
+    required: false,
+    appliesTo: ["form", "detail"],
+    example: '[{ name: "email", type: "input", label: "Email", required: true }]'
+  },
+  {
+    id: "detailSections",
+    label: "Detail sections",
+    description: "Cards or sections for detail pages such as profile, activity, permissions, or related records.",
+    required: false,
+    appliesTo: ["detail"],
+    example: '[{ title: "Profile" }, { title: "Recent activity" }]'
+  },
+  {
+    id: "emptyState",
+    label: "Empty state",
+    description: "Fallback title, description, and action when there is no data.",
+    required: false,
+    appliesTo: ["list", "dashboard", "detail"],
+    example: '{ title: "No users yet", description: "Create the first user to get started." }'
+  },
+  {
+    id: "permissions",
+    label: "Permissions",
+    description: "Permission keys that affect sidebar visibility or action availability.",
+    required: false,
+    appliesTo: ["all"],
+    example: '["user.read", "user.write"]'
+  }
+];
+var uiScreenBlueprint = {
+  pageKinds: [
+    {
+      id: "list",
+      label: "List page",
+      frame: [
+        "Sidebar shell",
+        "Breadcrumb",
+        "PageTitle with actions",
+        "Optional stats",
+        "Filter card",
+        "DataTable card"
+      ]
+    },
+    {
+      id: "form",
+      label: "Form page",
+      frame: [
+        "Sidebar shell",
+        "Breadcrumb",
+        "PageTitle with primary and cancel actions",
+        "Sectioned form cards",
+        "Bottom action row"
+      ]
+    },
+    {
+      id: "detail",
+      label: "Detail page",
+      frame: [
+        "Sidebar shell",
+        "Breadcrumb",
+        "PageTitle with status/actions",
+        "Summary stats or metadata card",
+        "Detail cards and related tables"
+      ]
+    },
+    {
+      id: "dashboard",
+      label: "Dashboard page",
+      frame: [
+        "Sidebar shell",
+        "Breadcrumb",
+        "PageTitle with actions",
+        "Stat cards row",
+        "Filters",
+        "Main insight cards and tables"
+      ]
+    }
+  ],
+  workflow: [
+    "Collect the screen brief before coding. Do not invent sidebar items, route urls, filters, fields, or table columns if the brief is missing.",
+    "Use Sidebar plus Breadcrumb and PageTitle to lock the shell before building the page body.",
+    "Choose only canonical root exports from @lucasvu/scope-ui.",
+    "Use Card and ui-grid utilities to create the frame first, then place controls and data components inside.",
+    "Keep all palette, radius, surface, and shadow decisions in the shared ui-theme.css preset file.",
+    "End with a consistency check against the selected preset and the screen brief."
+  ],
+  briefFields: uiScreenBriefFields
+};
+
 // src/theme-contract.ts
 var uiThemePresets = [
   {
@@ -7296,5 +7504,7 @@ exports.hasActiveDescendant = hasActiveDescendant;
 exports.uiAiManifest = uiAiManifest;
 exports.uiDefaultThemePreset = uiDefaultThemePreset;
 exports.uiProjectAiRules = uiProjectAiRules;
+exports.uiScreenBlueprint = uiScreenBlueprint;
+exports.uiScreenBriefFields = uiScreenBriefFields;
 exports.uiThemeContract = uiThemeContract;
 exports.uiThemePresets = uiThemePresets;

package/dist/index.d.cts

@@ -875,7 +875,7 @@ type UiAiComponentDescriptor = {
 declare const uiAiManifest: {
     readonly packageName: "@lucasvu/scope-ui";
     readonly styleImport: "@lucasvu/scope-ui/styles.css";
-    readonly rules: readonly ["Import the stylesheet once at the app entry before rendering any component.", "If the project declares an approved theme preset in AGENTS.md or ui-theme.css, stay inside that preset and do not invent a second palette.", "Prefer the canonical component for each intent instead of mixing legacy MainFe components.", "Use Input/Textarea/Select label props directly for simple fields; use Field only to wrap custom controls or grouped content.", "Use Select for small fixed option lists, SearchableSelect for larger local lists, Combobox for type-and-pick flows, and AsyncCombobox for remote search.", "Always provide a stable rowKey to DataTable and use sortMode=\"server\" when sorting happens on the backend.", "Prefer Card as the outer layout section and keep alerts, stats, and tables inside CardContent when building dashboards or forms.", "Do not import MainFe components unless the target explicitly asks for legacy main-fe styling."];
+    readonly rules: readonly ["Import the stylesheet once at the app entry before rendering any component.", "If the project declares an approved theme preset in AGENTS.md or ui-theme.css, stay inside that preset and do not invent a second palette.", "Collect the screen brief first: route url, sidebar items, active sidebar item, page title, actions, and the page-specific content schema.", "Prefer the canonical component for each intent instead of mixing legacy MainFe components.", "Use Input/Textarea/Select label props directly for simple fields; use Field only to wrap custom controls or grouped content.", "Use Select for small fixed option lists, SearchableSelect for larger local lists, Combobox for type-and-pick flows, and AsyncCombobox for remote search.", "Always provide a stable rowKey to DataTable and use sortMode=\"server\" when sorting happens on the backend.", "Prefer Card as the outer layout section and keep alerts, stats, and tables inside CardContent when building dashboards or forms.", "Do not import MainFe components unless the target explicitly asks for legacy main-fe styling."];
     readonly components: ({
         name: string;
         importName: string;
@@ -911,6 +911,290 @@ declare const uiAiManifest: {
     })[];
 };
 
+type UiScreenKind = 'list' | 'form' | 'detail' | 'dashboard';
+type UiScreenBriefField = {
+    id: string;
+    label: string;
+    description: string;
+    required: boolean;
+    appliesTo: UiScreenKind[] | ['all'];
+    example: string;
+};
+declare const uiScreenBriefFields: readonly [{
+    readonly id: "pageKind";
+    readonly label: "Page kind";
+    readonly description: "Choose the base recipe for the screen.";
+    readonly required: true;
+    readonly appliesTo: ["all"];
+    readonly example: "list";
+}, {
+    readonly id: "routeUrl";
+    readonly label: "Route URL";
+    readonly description: "Final route for the screen or feature entry.";
+    readonly required: true;
+    readonly appliesTo: ["all"];
+    readonly example: "/admin/users";
+}, {
+    readonly id: "sidebarItems";
+    readonly label: "Sidebar items";
+    readonly description: "Sidebar entries with at least id, title, and href so the shell stays consistent.";
+    readonly required: true;
+    readonly appliesTo: ["all"];
+    readonly example: "[{ id: \"users\", title: \"Users\", href: \"/admin/users\" }]";
+}, {
+    readonly id: "activeSidebarItemId";
+    readonly label: "Active sidebar item id";
+    readonly description: "The sidebar item that should appear active on this screen.";
+    readonly required: true;
+    readonly appliesTo: ["all"];
+    readonly example: "users";
+}, {
+    readonly id: "breadcrumbs";
+    readonly label: "Breadcrumbs";
+    readonly description: "Ordered breadcrumb items for the page header.";
+    readonly required: false;
+    readonly appliesTo: ["all"];
+    readonly example: "[{ label: \"Admin\", href: \"/admin\" }, { label: \"Users\", current: true }]";
+}, {
+    readonly id: "pageTitle";
+    readonly label: "Page title";
+    readonly description: "Main page heading shown in the content header.";
+    readonly required: true;
+    readonly appliesTo: ["all"];
+    readonly example: "Users";
+}, {
+    readonly id: "pageSubtitle";
+    readonly label: "Page subtitle";
+    readonly description: "Short supporting text under the title.";
+    readonly required: false;
+    readonly appliesTo: ["all"];
+    readonly example: "Manage internal user accounts and permissions.";
+}, {
+    readonly id: "primaryAction";
+    readonly label: "Primary action";
+    readonly description: "The highest-emphasis action shown in the page header.";
+    readonly required: false;
+    readonly appliesTo: ["all"];
+    readonly example: "{ label: \"Create user\", href: \"/admin/users/create\" }";
+}, {
+    readonly id: "secondaryActions";
+    readonly label: "Secondary actions";
+    readonly description: "Additional header actions such as export, refresh, or cancel.";
+    readonly required: false;
+    readonly appliesTo: ["all"];
+    readonly example: "[{ label: \"Export\" }, { label: \"Refresh\" }]";
+}, {
+    readonly id: "summaryStats";
+    readonly label: "Summary stats";
+    readonly description: "Top-line numbers for dashboard or overview screens.";
+    readonly required: false;
+    readonly appliesTo: ["dashboard", "detail"];
+    readonly example: "[{ label: \"Active users\", value: \"1,204\", trend: \"up\", delta: \"+12%\" }]";
+}, {
+    readonly id: "filters";
+    readonly label: "Filters";
+    readonly description: "Filter bar controls shown above list or dashboard content.";
+    readonly required: false;
+    readonly appliesTo: ["list", "dashboard"];
+    readonly example: "[{ type: \"search\", label: \"Search user\" }, { type: \"select\", label: \"Role\" }]";
+}, {
+    readonly id: "tableColumns";
+    readonly label: "Table columns";
+    readonly description: "Columns for a list table, including label and render intent.";
+    readonly required: false;
+    readonly appliesTo: ["list", "detail", "dashboard"];
+    readonly example: "[{ key: \"name\", title: \"Name\" }, { key: \"role\", title: \"Role\" }]";
+}, {
+    readonly id: "rowActions";
+    readonly label: "Row actions";
+    readonly description: "Per-row actions for table screens.";
+    readonly required: false;
+    readonly appliesTo: ["list", "detail"];
+    readonly example: "[{ label: \"Edit\" }, { label: \"Reset password\" }]";
+}, {
+    readonly id: "formSections";
+    readonly label: "Form sections";
+    readonly description: "Grouped form sections and the fields inside each section.";
+    readonly required: false;
+    readonly appliesTo: ["form"];
+    readonly example: "[{ title: \"Basic info\", fields: [\"name\", \"email\", \"role\"] }]";
+}, {
+    readonly id: "fields";
+    readonly label: "Fields";
+    readonly description: "Detailed field list with type, label, required state, and helper text.";
+    readonly required: false;
+    readonly appliesTo: ["form", "detail"];
+    readonly example: "[{ name: \"email\", type: \"input\", label: \"Email\", required: true }]";
+}, {
+    readonly id: "detailSections";
+    readonly label: "Detail sections";
+    readonly description: "Cards or sections for detail pages such as profile, activity, permissions, or related records.";
+    readonly required: false;
+    readonly appliesTo: ["detail"];
+    readonly example: "[{ title: \"Profile\" }, { title: \"Recent activity\" }]";
+}, {
+    readonly id: "emptyState";
+    readonly label: "Empty state";
+    readonly description: "Fallback title, description, and action when there is no data.";
+    readonly required: false;
+    readonly appliesTo: ["list", "dashboard", "detail"];
+    readonly example: "{ title: \"No users yet\", description: \"Create the first user to get started.\" }";
+}, {
+    readonly id: "permissions";
+    readonly label: "Permissions";
+    readonly description: "Permission keys that affect sidebar visibility or action availability.";
+    readonly required: false;
+    readonly appliesTo: ["all"];
+    readonly example: "[\"user.read\", \"user.write\"]";
+}];
+declare const uiScreenBlueprint: {
+    readonly pageKinds: readonly [{
+        readonly id: "list";
+        readonly label: "List page";
+        readonly frame: readonly ["Sidebar shell", "Breadcrumb", "PageTitle with actions", "Optional stats", "Filter card", "DataTable card"];
+    }, {
+        readonly id: "form";
+        readonly label: "Form page";
+        readonly frame: readonly ["Sidebar shell", "Breadcrumb", "PageTitle with primary and cancel actions", "Sectioned form cards", "Bottom action row"];
+    }, {
+        readonly id: "detail";
+        readonly label: "Detail page";
+        readonly frame: readonly ["Sidebar shell", "Breadcrumb", "PageTitle with status/actions", "Summary stats or metadata card", "Detail cards and related tables"];
+    }, {
+        readonly id: "dashboard";
+        readonly label: "Dashboard page";
+        readonly frame: readonly ["Sidebar shell", "Breadcrumb", "PageTitle with actions", "Stat cards row", "Filters", "Main insight cards and tables"];
+    }];
+    readonly workflow: readonly ["Collect the screen brief before coding. Do not invent sidebar items, route urls, filters, fields, or table columns if the brief is missing.", "Use Sidebar plus Breadcrumb and PageTitle to lock the shell before building the page body.", "Choose only canonical root exports from @lucasvu/scope-ui.", "Use Card and ui-grid utilities to create the frame first, then place controls and data components inside.", "Keep all palette, radius, surface, and shadow decisions in the shared ui-theme.css preset file.", "End with a consistency check against the selected preset and the screen brief."];
+    readonly briefFields: readonly [{
+        readonly id: "pageKind";
+        readonly label: "Page kind";
+        readonly description: "Choose the base recipe for the screen.";
+        readonly required: true;
+        readonly appliesTo: ["all"];
+        readonly example: "list";
+    }, {
+        readonly id: "routeUrl";
+        readonly label: "Route URL";
+        readonly description: "Final route for the screen or feature entry.";
+        readonly required: true;
+        readonly appliesTo: ["all"];
+        readonly example: "/admin/users";
+    }, {
+        readonly id: "sidebarItems";
+        readonly label: "Sidebar items";
+        readonly description: "Sidebar entries with at least id, title, and href so the shell stays consistent.";
+        readonly required: true;
+        readonly appliesTo: ["all"];
+        readonly example: "[{ id: \"users\", title: \"Users\", href: \"/admin/users\" }]";
+    }, {
+        readonly id: "activeSidebarItemId";
+        readonly label: "Active sidebar item id";
+        readonly description: "The sidebar item that should appear active on this screen.";
+        readonly required: true;
+        readonly appliesTo: ["all"];
+        readonly example: "users";
+    }, {
+        readonly id: "breadcrumbs";
+        readonly label: "Breadcrumbs";
+        readonly description: "Ordered breadcrumb items for the page header.";
+        readonly required: false;
+        readonly appliesTo: ["all"];
+        readonly example: "[{ label: \"Admin\", href: \"/admin\" }, { label: \"Users\", current: true }]";
+    }, {
+        readonly id: "pageTitle";
+        readonly label: "Page title";
+        readonly description: "Main page heading shown in the content header.";
+        readonly required: true;
+        readonly appliesTo: ["all"];
+        readonly example: "Users";
+    }, {
+        readonly id: "pageSubtitle";
+        readonly label: "Page subtitle";
+        readonly description: "Short supporting text under the title.";
+        readonly required: false;
+        readonly appliesTo: ["all"];
+        readonly example: "Manage internal user accounts and permissions.";
+    }, {
+        readonly id: "primaryAction";
+        readonly label: "Primary action";
+        readonly description: "The highest-emphasis action shown in the page header.";
+        readonly required: false;
+        readonly appliesTo: ["all"];
+        readonly example: "{ label: \"Create user\", href: \"/admin/users/create\" }";
+    }, {
+        readonly id: "secondaryActions";
+        readonly label: "Secondary actions";
+        readonly description: "Additional header actions such as export, refresh, or cancel.";
+        readonly required: false;
+        readonly appliesTo: ["all"];
+        readonly example: "[{ label: \"Export\" }, { label: \"Refresh\" }]";
+    }, {
+        readonly id: "summaryStats";
+        readonly label: "Summary stats";
+        readonly description: "Top-line numbers for dashboard or overview screens.";
+        readonly required: false;
+        readonly appliesTo: ["dashboard", "detail"];
+        readonly example: "[{ label: \"Active users\", value: \"1,204\", trend: \"up\", delta: \"+12%\" }]";
+    }, {
+        readonly id: "filters";
+        readonly label: "Filters";
+        readonly description: "Filter bar controls shown above list or dashboard content.";
+        readonly required: false;
+        readonly appliesTo: ["list", "dashboard"];
+        readonly example: "[{ type: \"search\", label: \"Search user\" }, { type: \"select\", label: \"Role\" }]";
+    }, {
+        readonly id: "tableColumns";
+        readonly label: "Table columns";
+        readonly description: "Columns for a list table, including label and render intent.";
+        readonly required: false;
+        readonly appliesTo: ["list", "detail", "dashboard"];
+        readonly example: "[{ key: \"name\", title: \"Name\" }, { key: \"role\", title: \"Role\" }]";
+    }, {
+        readonly id: "rowActions";
+        readonly label: "Row actions";
+        readonly description: "Per-row actions for table screens.";
+        readonly required: false;
+        readonly appliesTo: ["list", "detail"];
+        readonly example: "[{ label: \"Edit\" }, { label: \"Reset password\" }]";
+    }, {
+        readonly id: "formSections";
+        readonly label: "Form sections";
+        readonly description: "Grouped form sections and the fields inside each section.";
+        readonly required: false;
+        readonly appliesTo: ["form"];
+        readonly example: "[{ title: \"Basic info\", fields: [\"name\", \"email\", \"role\"] }]";
+    }, {
+        readonly id: "fields";
+        readonly label: "Fields";
+        readonly description: "Detailed field list with type, label, required state, and helper text.";
+        readonly required: false;
+        readonly appliesTo: ["form", "detail"];
+        readonly example: "[{ name: \"email\", type: \"input\", label: \"Email\", required: true }]";
+    }, {
+        readonly id: "detailSections";
+        readonly label: "Detail sections";
+        readonly description: "Cards or sections for detail pages such as profile, activity, permissions, or related records.";
+        readonly required: false;
+        readonly appliesTo: ["detail"];
+        readonly example: "[{ title: \"Profile\" }, { title: \"Recent activity\" }]";
+    }, {
+        readonly id: "emptyState";
+        readonly label: "Empty state";
+        readonly description: "Fallback title, description, and action when there is no data.";
+        readonly required: false;
+        readonly appliesTo: ["list", "dashboard", "detail"];
+        readonly example: "{ title: \"No users yet\", description: \"Create the first user to get started.\" }";
+    }, {
+        readonly id: "permissions";
+        readonly label: "Permissions";
+        readonly description: "Permission keys that affect sidebar visibility or action availability.";
+        readonly required: false;
+        readonly appliesTo: ["all"];
+        readonly example: "[\"user.read\", \"user.write\"]";
+    }];
+};
+
 type UiThemeToken = {
     name: string;
     description: string;
@@ -1342,4 +1626,4 @@ declare const uiProjectAiRules: readonly ["Use @lucasvu/scope-ui as the default
 type ClassValue = string | false | null | undefined;
 declare function cn(...values: ClassValue[]): string;
 
-export { Alert, type AlertProps, ArgonSidebar, AsyncCombobox, type AsyncComboboxProps, Badge, type BadgeProps, Breadcrumb, type BreadcrumbItem, Button$1 as Button, type ButtonProps$1 as ButtonProps, Card$1 as Card, CardAction$1 as CardAction, CardContent$1 as CardContent, CardDescription$1 as CardDescription, CardFooter$1 as CardFooter, CardHeader$1 as CardHeader, CardTitle$1 as CardTitle, Combobox$1 as Combobox, type ComboboxOption$2 as ComboboxOption, FormControl as Control, DataTable$1 as DataTable, type DataTableAlign$1 as DataTableAlign, type DataTableColumn$1 as DataTableColumn, type DataTablePagination$1 as DataTablePagination, type DataTableProps$1 as DataTableProps, type DataTableRowSelection$1 as DataTableRowSelection, type DataTableSortDirection$1 as DataTableSortDirection, type DataTableSortState$1 as DataTableSortState, FormDescription as Description, FormField as Field, Form, FormControl, FormDescription, FormField, type FormFieldProps, FormItem, FormLabel, FormMessage, Input$1 as Input, type InputProps$1 as InputProps, FormItem as Item, FormLabel as Label, LineClampTooltip, type LineClampTooltipProps, Loading, type LoadingProps, index as MainFe, FormMessage as Message, MultiSelect, type MultiSelectOption, NumericInput, type NumericInputProps, type Option, OverflowTooltip, type OverflowTooltipProps, PageTitle$1 as PageTitle, Pagination, type PaginationInfo, type PaginationProps, type PermissionChecker, SearchableSelect, type SearchableSelectOption, type SearchableSelectProps, SectionTitle$1 as SectionTitle, Select, type SelectOption, type SelectProps, Sidebar, SidebarItem, type SidebarProps, Stat, type StatProps, type TabItem, Table$1 as Table, TableBody$1 as TableBody, TableCell$1 as TableCell, TableHeader$1 as TableHeader, TableRow$1 as TableRow, Tabs, type TabsProps, Textarea, type TextareaProps, Tooltip, type Trend, TruncatedText, type TruncatedTextProps, type UiAiComponentDescriptor, type UiAiComponentProp, type UiThemePreset, type UiThemeToken, cn, defaultPermissionChecker, filterSidebarItems, hasActiveDescendant, uiAiManifest, uiDefaultThemePreset, uiProjectAiRules, uiThemeContract, uiThemePresets };
+export { Alert, type AlertProps, ArgonSidebar, AsyncCombobox, type AsyncComboboxProps, Badge, type BadgeProps, Breadcrumb, type BreadcrumbItem, Button$1 as Button, type ButtonProps$1 as ButtonProps, Card$1 as Card, CardAction$1 as CardAction, CardContent$1 as CardContent, CardDescription$1 as CardDescription, CardFooter$1 as CardFooter, CardHeader$1 as CardHeader, CardTitle$1 as CardTitle, Combobox$1 as Combobox, type ComboboxOption$2 as ComboboxOption, FormControl as Control, DataTable$1 as DataTable, type DataTableAlign$1 as DataTableAlign, type DataTableColumn$1 as DataTableColumn, type DataTablePagination$1 as DataTablePagination, type DataTableProps$1 as DataTableProps, type DataTableRowSelection$1 as DataTableRowSelection, type DataTableSortDirection$1 as DataTableSortDirection, type DataTableSortState$1 as DataTableSortState, FormDescription as Description, FormField as Field, Form, FormControl, FormDescription, FormField, type FormFieldProps, FormItem, FormLabel, FormMessage, Input$1 as Input, type InputProps$1 as InputProps, FormItem as Item, FormLabel as Label, LineClampTooltip, type LineClampTooltipProps, Loading, type LoadingProps, index as MainFe, FormMessage as Message, MultiSelect, type MultiSelectOption, NumericInput, type NumericInputProps, type Option, OverflowTooltip, type OverflowTooltipProps, PageTitle$1 as PageTitle, Pagination, type PaginationInfo, type PaginationProps, type PermissionChecker, SearchableSelect, type SearchableSelectOption, type SearchableSelectProps, SectionTitle$1 as SectionTitle, Select, type SelectOption, type SelectProps, Sidebar, SidebarItem, type SidebarProps, Stat, type StatProps, type TabItem, Table$1 as Table, TableBody$1 as TableBody, TableCell$1 as TableCell, TableHeader$1 as TableHeader, TableRow$1 as TableRow, Tabs, type TabsProps, Textarea, type TextareaProps, Tooltip, type Trend, TruncatedText, type TruncatedTextProps, type UiAiComponentDescriptor, type UiAiComponentProp, type UiScreenBriefField, type UiScreenKind, type UiThemePreset, type UiThemeToken, cn, defaultPermissionChecker, filterSidebarItems, hasActiveDescendant, uiAiManifest, uiDefaultThemePreset, uiProjectAiRules, uiScreenBlueprint, uiScreenBriefFields, uiThemeContract, uiThemePresets };

package/dist/index.d.ts

@@ -875,7 +875,7 @@ type UiAiComponentDescriptor = {
 declare const uiAiManifest: {
     readonly packageName: "@lucasvu/scope-ui";
     readonly styleImport: "@lucasvu/scope-ui/styles.css";
-    readonly rules: readonly ["Import the stylesheet once at the app entry before rendering any component.", "If the project declares an approved theme preset in AGENTS.md or ui-theme.css, stay inside that preset and do not invent a second palette.", "Prefer the canonical component for each intent instead of mixing legacy MainFe components.", "Use Input/Textarea/Select label props directly for simple fields; use Field only to wrap custom controls or grouped content.", "Use Select for small fixed option lists, SearchableSelect for larger local lists, Combobox for type-and-pick flows, and AsyncCombobox for remote search.", "Always provide a stable rowKey to DataTable and use sortMode=\"server\" when sorting happens on the backend.", "Prefer Card as the outer layout section and keep alerts, stats, and tables inside CardContent when building dashboards or forms.", "Do not import MainFe components unless the target explicitly asks for legacy main-fe styling."];
+    readonly rules: readonly ["Import the stylesheet once at the app entry before rendering any component.", "If the project declares an approved theme preset in AGENTS.md or ui-theme.css, stay inside that preset and do not invent a second palette.", "Collect the screen brief first: route url, sidebar items, active sidebar item, page title, actions, and the page-specific content schema.", "Prefer the canonical component for each intent instead of mixing legacy MainFe components.", "Use Input/Textarea/Select label props directly for simple fields; use Field only to wrap custom controls or grouped content.", "Use Select for small fixed option lists, SearchableSelect for larger local lists, Combobox for type-and-pick flows, and AsyncCombobox for remote search.", "Always provide a stable rowKey to DataTable and use sortMode=\"server\" when sorting happens on the backend.", "Prefer Card as the outer layout section and keep alerts, stats, and tables inside CardContent when building dashboards or forms.", "Do not import MainFe components unless the target explicitly asks for legacy main-fe styling."];
     readonly components: ({
         name: string;
         importName: string;
@@ -911,6 +911,290 @@ declare const uiAiManifest: {
     })[];
 };
 
+type UiScreenKind = 'list' | 'form' | 'detail' | 'dashboard';
+type UiScreenBriefField = {
+    id: string;
+    label: string;
+    description: string;
+    required: boolean;
+    appliesTo: UiScreenKind[] | ['all'];
+    example: string;
+};
+declare const uiScreenBriefFields: readonly [{
+    readonly id: "pageKind";
+    readonly label: "Page kind";
+    readonly description: "Choose the base recipe for the screen.";
+    readonly required: true;
+    readonly appliesTo: ["all"];
+    readonly example: "list";
+}, {
+    readonly id: "routeUrl";
+    readonly label: "Route URL";
+    readonly description: "Final route for the screen or feature entry.";
+    readonly required: true;
+    readonly appliesTo: ["all"];
+    readonly example: "/admin/users";
+}, {
+    readonly id: "sidebarItems";
+    readonly label: "Sidebar items";
+    readonly description: "Sidebar entries with at least id, title, and href so the shell stays consistent.";
+    readonly required: true;
+    readonly appliesTo: ["all"];
+    readonly example: "[{ id: \"users\", title: \"Users\", href: \"/admin/users\" }]";
+}, {
+    readonly id: "activeSidebarItemId";
+    readonly label: "Active sidebar item id";
+    readonly description: "The sidebar item that should appear active on this screen.";
+    readonly required: true;
+    readonly appliesTo: ["all"];
+    readonly example: "users";
+}, {
+    readonly id: "breadcrumbs";
+    readonly label: "Breadcrumbs";
+    readonly description: "Ordered breadcrumb items for the page header.";
+    readonly required: false;
+    readonly appliesTo: ["all"];
+    readonly example: "[{ label: \"Admin\", href: \"/admin\" }, { label: \"Users\", current: true }]";
+}, {
+    readonly id: "pageTitle";
+    readonly label: "Page title";
+    readonly description: "Main page heading shown in the content header.";
+    readonly required: true;
+    readonly appliesTo: ["all"];
+    readonly example: "Users";
+}, {
+    readonly id: "pageSubtitle";
+    readonly label: "Page subtitle";
+    readonly description: "Short supporting text under the title.";
+    readonly required: false;
+    readonly appliesTo: ["all"];
+    readonly example: "Manage internal user accounts and permissions.";
+}, {
+    readonly id: "primaryAction";
+    readonly label: "Primary action";
+    readonly description: "The highest-emphasis action shown in the page header.";
+    readonly required: false;
+    readonly appliesTo: ["all"];
+    readonly example: "{ label: \"Create user\", href: \"/admin/users/create\" }";
+}, {
+    readonly id: "secondaryActions";
+    readonly label: "Secondary actions";
+    readonly description: "Additional header actions such as export, refresh, or cancel.";
+    readonly required: false;
+    readonly appliesTo: ["all"];
+    readonly example: "[{ label: \"Export\" }, { label: \"Refresh\" }]";
+}, {
+    readonly id: "summaryStats";
+    readonly label: "Summary stats";
+    readonly description: "Top-line numbers for dashboard or overview screens.";
+    readonly required: false;
+    readonly appliesTo: ["dashboard", "detail"];
+    readonly example: "[{ label: \"Active users\", value: \"1,204\", trend: \"up\", delta: \"+12%\" }]";
+}, {
+    readonly id: "filters";
+    readonly label: "Filters";
+    readonly description: "Filter bar controls shown above list or dashboard content.";
+    readonly required: false;
+    readonly appliesTo: ["list", "dashboard"];
+    readonly example: "[{ type: \"search\", label: \"Search user\" }, { type: \"select\", label: \"Role\" }]";
+}, {
+    readonly id: "tableColumns";
+    readonly label: "Table columns";
+    readonly description: "Columns for a list table, including label and render intent.";
+    readonly required: false;
+    readonly appliesTo: ["list", "detail", "dashboard"];
+    readonly example: "[{ key: \"name\", title: \"Name\" }, { key: \"role\", title: \"Role\" }]";
+}, {
+    readonly id: "rowActions";
+    readonly label: "Row actions";
+    readonly description: "Per-row actions for table screens.";
+    readonly required: false;
+    readonly appliesTo: ["list", "detail"];
+    readonly example: "[{ label: \"Edit\" }, { label: \"Reset password\" }]";
+}, {
+    readonly id: "formSections";
+    readonly label: "Form sections";
+    readonly description: "Grouped form sections and the fields inside each section.";
+    readonly required: false;
+    readonly appliesTo: ["form"];
+    readonly example: "[{ title: \"Basic info\", fields: [\"name\", \"email\", \"role\"] }]";
+}, {
+    readonly id: "fields";
+    readonly label: "Fields";
+    readonly description: "Detailed field list with type, label, required state, and helper text.";
+    readonly required: false;
+    readonly appliesTo: ["form", "detail"];
+    readonly example: "[{ name: \"email\", type: \"input\", label: \"Email\", required: true }]";
+}, {
+    readonly id: "detailSections";
+    readonly label: "Detail sections";
+    readonly description: "Cards or sections for detail pages such as profile, activity, permissions, or related records.";
+    readonly required: false;
+    readonly appliesTo: ["detail"];
+    readonly example: "[{ title: \"Profile\" }, { title: \"Recent activity\" }]";
+}, {
+    readonly id: "emptyState";
+    readonly label: "Empty state";
+    readonly description: "Fallback title, description, and action when there is no data.";
+    readonly required: false;
+    readonly appliesTo: ["list", "dashboard", "detail"];
+    readonly example: "{ title: \"No users yet\", description: \"Create the first user to get started.\" }";
+}, {
+    readonly id: "permissions";
+    readonly label: "Permissions";
+    readonly description: "Permission keys that affect sidebar visibility or action availability.";
+    readonly required: false;
+    readonly appliesTo: ["all"];
+    readonly example: "[\"user.read\", \"user.write\"]";
+}];
+declare const uiScreenBlueprint: {
+    readonly pageKinds: readonly [{
+        readonly id: "list";
+        readonly label: "List page";
+        readonly frame: readonly ["Sidebar shell", "Breadcrumb", "PageTitle with actions", "Optional stats", "Filter card", "DataTable card"];
+    }, {
+        readonly id: "form";
+        readonly label: "Form page";
+        readonly frame: readonly ["Sidebar shell", "Breadcrumb", "PageTitle with primary and cancel actions", "Sectioned form cards", "Bottom action row"];
+    }, {
+        readonly id: "detail";
+        readonly label: "Detail page";
+        readonly frame: readonly ["Sidebar shell", "Breadcrumb", "PageTitle with status/actions", "Summary stats or metadata card", "Detail cards and related tables"];
+    }, {
+        readonly id: "dashboard";
+        readonly label: "Dashboard page";
+        readonly frame: readonly ["Sidebar shell", "Breadcrumb", "PageTitle with actions", "Stat cards row", "Filters", "Main insight cards and tables"];
+    }];
+    readonly workflow: readonly ["Collect the screen brief before coding. Do not invent sidebar items, route urls, filters, fields, or table columns if the brief is missing.", "Use Sidebar plus Breadcrumb and PageTitle to lock the shell before building the page body.", "Choose only canonical root exports from @lucasvu/scope-ui.", "Use Card and ui-grid utilities to create the frame first, then place controls and data components inside.", "Keep all palette, radius, surface, and shadow decisions in the shared ui-theme.css preset file.", "End with a consistency check against the selected preset and the screen brief."];
+    readonly briefFields: readonly [{
+        readonly id: "pageKind";
+        readonly label: "Page kind";
+        readonly description: "Choose the base recipe for the screen.";
+        readonly required: true;
+        readonly appliesTo: ["all"];
+        readonly example: "list";
+    }, {
+        readonly id: "routeUrl";
+        readonly label: "Route URL";
+        readonly description: "Final route for the screen or feature entry.";
+        readonly required: true;
+        readonly appliesTo: ["all"];
+        readonly example: "/admin/users";
+    }, {
+        readonly id: "sidebarItems";
+        readonly label: "Sidebar items";
+        readonly description: "Sidebar entries with at least id, title, and href so the shell stays consistent.";
+        readonly required: true;
+        readonly appliesTo: ["all"];
+        readonly example: "[{ id: \"users\", title: \"Users\", href: \"/admin/users\" }]";
+    }, {
+        readonly id: "activeSidebarItemId";
+        readonly label: "Active sidebar item id";
+        readonly description: "The sidebar item that should appear active on this screen.";
+        readonly required: true;
+        readonly appliesTo: ["all"];
+        readonly example: "users";
+    }, {
+        readonly id: "breadcrumbs";
+        readonly label: "Breadcrumbs";
+        readonly description: "Ordered breadcrumb items for the page header.";
+        readonly required: false;
+        readonly appliesTo: ["all"];
+        readonly example: "[{ label: \"Admin\", href: \"/admin\" }, { label: \"Users\", current: true }]";
+    }, {
+        readonly id: "pageTitle";
+        readonly label: "Page title";
+        readonly description: "Main page heading shown in the content header.";
+        readonly required: true;
+        readonly appliesTo: ["all"];
+        readonly example: "Users";
+    }, {
+        readonly id: "pageSubtitle";
+        readonly label: "Page subtitle";
+        readonly description: "Short supporting text under the title.";
+        readonly required: false;
+        readonly appliesTo: ["all"];
+        readonly example: "Manage internal user accounts and permissions.";
+    }, {
+        readonly id: "primaryAction";
+        readonly label: "Primary action";
+        readonly description: "The highest-emphasis action shown in the page header.";
+        readonly required: false;
+        readonly appliesTo: ["all"];
+        readonly example: "{ label: \"Create user\", href: \"/admin/users/create\" }";
+    }, {
+        readonly id: "secondaryActions";
+        readonly label: "Secondary actions";
+        readonly description: "Additional header actions such as export, refresh, or cancel.";
+        readonly required: false;
+        readonly appliesTo: ["all"];
+        readonly example: "[{ label: \"Export\" }, { label: \"Refresh\" }]";
+    }, {
+        readonly id: "summaryStats";
+        readonly label: "Summary stats";
+        readonly description: "Top-line numbers for dashboard or overview screens.";
+        readonly required: false;
+        readonly appliesTo: ["dashboard", "detail"];
+        readonly example: "[{ label: \"Active users\", value: \"1,204\", trend: \"up\", delta: \"+12%\" }]";
+    }, {
+        readonly id: "filters";
+        readonly label: "Filters";
+        readonly description: "Filter bar controls shown above list or dashboard content.";
+        readonly required: false;
+        readonly appliesTo: ["list", "dashboard"];
+        readonly example: "[{ type: \"search\", label: \"Search user\" }, { type: \"select\", label: \"Role\" }]";
+    }, {
+        readonly id: "tableColumns";
+        readonly label: "Table columns";
+        readonly description: "Columns for a list table, including label and render intent.";
+        readonly required: false;
+        readonly appliesTo: ["list", "detail", "dashboard"];
+        readonly example: "[{ key: \"name\", title: \"Name\" }, { key: \"role\", title: \"Role\" }]";
+    }, {
+        readonly id: "rowActions";
+        readonly label: "Row actions";
+        readonly description: "Per-row actions for table screens.";
+        readonly required: false;
+        readonly appliesTo: ["list", "detail"];
+        readonly example: "[{ label: \"Edit\" }, { label: \"Reset password\" }]";
+    }, {
+        readonly id: "formSections";
+        readonly label: "Form sections";
+        readonly description: "Grouped form sections and the fields inside each section.";
+        readonly required: false;
+        readonly appliesTo: ["form"];
+        readonly example: "[{ title: \"Basic info\", fields: [\"name\", \"email\", \"role\"] }]";
+    }, {
+        readonly id: "fields";
+        readonly label: "Fields";
+        readonly description: "Detailed field list with type, label, required state, and helper text.";
+        readonly required: false;
+        readonly appliesTo: ["form", "detail"];
+        readonly example: "[{ name: \"email\", type: \"input\", label: \"Email\", required: true }]";
+    }, {
+        readonly id: "detailSections";
+        readonly label: "Detail sections";
+        readonly description: "Cards or sections for detail pages such as profile, activity, permissions, or related records.";
+        readonly required: false;
+        readonly appliesTo: ["detail"];
+        readonly example: "[{ title: \"Profile\" }, { title: \"Recent activity\" }]";
+    }, {
+        readonly id: "emptyState";
+        readonly label: "Empty state";
+        readonly description: "Fallback title, description, and action when there is no data.";
+        readonly required: false;
+        readonly appliesTo: ["list", "dashboard", "detail"];
+        readonly example: "{ title: \"No users yet\", description: \"Create the first user to get started.\" }";
+    }, {
+        readonly id: "permissions";
+        readonly label: "Permissions";
+        readonly description: "Permission keys that affect sidebar visibility or action availability.";
+        readonly required: false;
+        readonly appliesTo: ["all"];
+        readonly example: "[\"user.read\", \"user.write\"]";
+    }];
+};
+
 type UiThemeToken = {
     name: string;
     description: string;
@@ -1342,4 +1626,4 @@ declare const uiProjectAiRules: readonly ["Use @lucasvu/scope-ui as the default
 type ClassValue = string | false | null | undefined;
 declare function cn(...values: ClassValue[]): string;
 
-export { Alert, type AlertProps, ArgonSidebar, AsyncCombobox, type AsyncComboboxProps, Badge, type BadgeProps, Breadcrumb, type BreadcrumbItem, Button$1 as Button, type ButtonProps$1 as ButtonProps, Card$1 as Card, CardAction$1 as CardAction, CardContent$1 as CardContent, CardDescription$1 as CardDescription, CardFooter$1 as CardFooter, CardHeader$1 as CardHeader, CardTitle$1 as CardTitle, Combobox$1 as Combobox, type ComboboxOption$2 as ComboboxOption, FormControl as Control, DataTable$1 as DataTable, type DataTableAlign$1 as DataTableAlign, type DataTableColumn$1 as DataTableColumn, type DataTablePagination$1 as DataTablePagination, type DataTableProps$1 as DataTableProps, type DataTableRowSelection$1 as DataTableRowSelection, type DataTableSortDirection$1 as DataTableSortDirection, type DataTableSortState$1 as DataTableSortState, FormDescription as Description, FormField as Field, Form, FormControl, FormDescription, FormField, type FormFieldProps, FormItem, FormLabel, FormMessage, Input$1 as Input, type InputProps$1 as InputProps, FormItem as Item, FormLabel as Label, LineClampTooltip, type LineClampTooltipProps, Loading, type LoadingProps, index as MainFe, FormMessage as Message, MultiSelect, type MultiSelectOption, NumericInput, type NumericInputProps, type Option, OverflowTooltip, type OverflowTooltipProps, PageTitle$1 as PageTitle, Pagination, type PaginationInfo, type PaginationProps, type PermissionChecker, SearchableSelect, type SearchableSelectOption, type SearchableSelectProps, SectionTitle$1 as SectionTitle, Select, type SelectOption, type SelectProps, Sidebar, SidebarItem, type SidebarProps, Stat, type StatProps, type TabItem, Table$1 as Table, TableBody$1 as TableBody, TableCell$1 as TableCell, TableHeader$1 as TableHeader, TableRow$1 as TableRow, Tabs, type TabsProps, Textarea, type TextareaProps, Tooltip, type Trend, TruncatedText, type TruncatedTextProps, type UiAiComponentDescriptor, type UiAiComponentProp, type UiThemePreset, type UiThemeToken, cn, defaultPermissionChecker, filterSidebarItems, hasActiveDescendant, uiAiManifest, uiDefaultThemePreset, uiProjectAiRules, uiThemeContract, uiThemePresets };
+export { Alert, type AlertProps, ArgonSidebar, AsyncCombobox, type AsyncComboboxProps, Badge, type BadgeProps, Breadcrumb, type BreadcrumbItem, Button$1 as Button, type ButtonProps$1 as ButtonProps, Card$1 as Card, CardAction$1 as CardAction, CardContent$1 as CardContent, CardDescription$1 as CardDescription, CardFooter$1 as CardFooter, CardHeader$1 as CardHeader, CardTitle$1 as CardTitle, Combobox$1 as Combobox, type ComboboxOption$2 as ComboboxOption, FormControl as Control, DataTable$1 as DataTable, type DataTableAlign$1 as DataTableAlign, type DataTableColumn$1 as DataTableColumn, type DataTablePagination$1 as DataTablePagination, type DataTableProps$1 as DataTableProps, type DataTableRowSelection$1 as DataTableRowSelection, type DataTableSortDirection$1 as DataTableSortDirection, type DataTableSortState$1 as DataTableSortState, FormDescription as Description, FormField as Field, Form, FormControl, FormDescription, FormField, type FormFieldProps, FormItem, FormLabel, FormMessage, Input$1 as Input, type InputProps$1 as InputProps, FormItem as Item, FormLabel as Label, LineClampTooltip, type LineClampTooltipProps, Loading, type LoadingProps, index as MainFe, FormMessage as Message, MultiSelect, type MultiSelectOption, NumericInput, type NumericInputProps, type Option, OverflowTooltip, type OverflowTooltipProps, PageTitle$1 as PageTitle, Pagination, type PaginationInfo, type PaginationProps, type PermissionChecker, SearchableSelect, type SearchableSelectOption, type SearchableSelectProps, SectionTitle$1 as SectionTitle, Select, type SelectOption, type SelectProps, Sidebar, SidebarItem, type SidebarProps, Stat, type StatProps, type TabItem, Table$1 as Table, TableBody$1 as TableBody, TableCell$1 as TableCell, TableHeader$1 as TableHeader, TableRow$1 as TableRow, Tabs, type TabsProps, Textarea, type TextareaProps, Tooltip, type Trend, TruncatedText, type TruncatedTextProps, type UiAiComponentDescriptor, type UiAiComponentProp, type UiScreenBriefField, type UiScreenKind, type UiThemePreset, type UiThemeToken, cn, defaultPermissionChecker, filterSidebarItems, hasActiveDescendant, uiAiManifest, uiDefaultThemePreset, uiProjectAiRules, uiScreenBlueprint, uiScreenBriefFields, uiThemeContract, uiThemePresets };

package/dist/index.js

@@ -6625,6 +6625,7 @@ var uiAiManifest = {
   rules: [
     "Import the stylesheet once at the app entry before rendering any component.",
     "If the project declares an approved theme preset in AGENTS.md or ui-theme.css, stay inside that preset and do not invent a second palette.",
+    "Collect the screen brief first: route url, sidebar items, active sidebar item, page title, actions, and the page-specific content schema.",
     "Prefer the canonical component for each intent instead of mixing legacy MainFe components.",
     "Use Input/Textarea/Select label props directly for simple fields; use Field only to wrap custom controls or grouped content.",
     "Use Select for small fixed option lists, SearchableSelect for larger local lists, Combobox for type-and-pick flows, and AsyncCombobox for remote search.",
@@ -6840,6 +6841,213 @@ var uiAiManifest = {
   ]
 };
 
+// src/screen-blueprint.ts
+var uiScreenBriefFields = [
+  {
+    id: "pageKind",
+    label: "Page kind",
+    description: "Choose the base recipe for the screen.",
+    required: true,
+    appliesTo: ["all"],
+    example: "list"
+  },
+  {
+    id: "routeUrl",
+    label: "Route URL",
+    description: "Final route for the screen or feature entry.",
+    required: true,
+    appliesTo: ["all"],
+    example: "/admin/users"
+  },
+  {
+    id: "sidebarItems",
+    label: "Sidebar items",
+    description: "Sidebar entries with at least id, title, and href so the shell stays consistent.",
+    required: true,
+    appliesTo: ["all"],
+    example: '[{ id: "users", title: "Users", href: "/admin/users" }]'
+  },
+  {
+    id: "activeSidebarItemId",
+    label: "Active sidebar item id",
+    description: "The sidebar item that should appear active on this screen.",
+    required: true,
+    appliesTo: ["all"],
+    example: "users"
+  },
+  {
+    id: "breadcrumbs",
+    label: "Breadcrumbs",
+    description: "Ordered breadcrumb items for the page header.",
+    required: false,
+    appliesTo: ["all"],
+    example: '[{ label: "Admin", href: "/admin" }, { label: "Users", current: true }]'
+  },
+  {
+    id: "pageTitle",
+    label: "Page title",
+    description: "Main page heading shown in the content header.",
+    required: true,
+    appliesTo: ["all"],
+    example: "Users"
+  },
+  {
+    id: "pageSubtitle",
+    label: "Page subtitle",
+    description: "Short supporting text under the title.",
+    required: false,
+    appliesTo: ["all"],
+    example: "Manage internal user accounts and permissions."
+  },
+  {
+    id: "primaryAction",
+    label: "Primary action",
+    description: "The highest-emphasis action shown in the page header.",
+    required: false,
+    appliesTo: ["all"],
+    example: '{ label: "Create user", href: "/admin/users/create" }'
+  },
+  {
+    id: "secondaryActions",
+    label: "Secondary actions",
+    description: "Additional header actions such as export, refresh, or cancel.",
+    required: false,
+    appliesTo: ["all"],
+    example: '[{ label: "Export" }, { label: "Refresh" }]'
+  },
+  {
+    id: "summaryStats",
+    label: "Summary stats",
+    description: "Top-line numbers for dashboard or overview screens.",
+    required: false,
+    appliesTo: ["dashboard", "detail"],
+    example: '[{ label: "Active users", value: "1,204", trend: "up", delta: "+12%" }]'
+  },
+  {
+    id: "filters",
+    label: "Filters",
+    description: "Filter bar controls shown above list or dashboard content.",
+    required: false,
+    appliesTo: ["list", "dashboard"],
+    example: '[{ type: "search", label: "Search user" }, { type: "select", label: "Role" }]'
+  },
+  {
+    id: "tableColumns",
+    label: "Table columns",
+    description: "Columns for a list table, including label and render intent.",
+    required: false,
+    appliesTo: ["list", "detail", "dashboard"],
+    example: '[{ key: "name", title: "Name" }, { key: "role", title: "Role" }]'
+  },
+  {
+    id: "rowActions",
+    label: "Row actions",
+    description: "Per-row actions for table screens.",
+    required: false,
+    appliesTo: ["list", "detail"],
+    example: '[{ label: "Edit" }, { label: "Reset password" }]'
+  },
+  {
+    id: "formSections",
+    label: "Form sections",
+    description: "Grouped form sections and the fields inside each section.",
+    required: false,
+    appliesTo: ["form"],
+    example: '[{ title: "Basic info", fields: ["name", "email", "role"] }]'
+  },
+  {
+    id: "fields",
+    label: "Fields",
+    description: "Detailed field list with type, label, required state, and helper text.",
+    required: false,
+    appliesTo: ["form", "detail"],
+    example: '[{ name: "email", type: "input", label: "Email", required: true }]'
+  },
+  {
+    id: "detailSections",
+    label: "Detail sections",
+    description: "Cards or sections for detail pages such as profile, activity, permissions, or related records.",
+    required: false,
+    appliesTo: ["detail"],
+    example: '[{ title: "Profile" }, { title: "Recent activity" }]'
+  },
+  {
+    id: "emptyState",
+    label: "Empty state",
+    description: "Fallback title, description, and action when there is no data.",
+    required: false,
+    appliesTo: ["list", "dashboard", "detail"],
+    example: '{ title: "No users yet", description: "Create the first user to get started." }'
+  },
+  {
+    id: "permissions",
+    label: "Permissions",
+    description: "Permission keys that affect sidebar visibility or action availability.",
+    required: false,
+    appliesTo: ["all"],
+    example: '["user.read", "user.write"]'
+  }
+];
+var uiScreenBlueprint = {
+  pageKinds: [
+    {
+      id: "list",
+      label: "List page",
+      frame: [
+        "Sidebar shell",
+        "Breadcrumb",
+        "PageTitle with actions",
+        "Optional stats",
+        "Filter card",
+        "DataTable card"
+      ]
+    },
+    {
+      id: "form",
+      label: "Form page",
+      frame: [
+        "Sidebar shell",
+        "Breadcrumb",
+        "PageTitle with primary and cancel actions",
+        "Sectioned form cards",
+        "Bottom action row"
+      ]
+    },
+    {
+      id: "detail",
+      label: "Detail page",
+      frame: [
+        "Sidebar shell",
+        "Breadcrumb",
+        "PageTitle with status/actions",
+        "Summary stats or metadata card",
+        "Detail cards and related tables"
+      ]
+    },
+    {
+      id: "dashboard",
+      label: "Dashboard page",
+      frame: [
+        "Sidebar shell",
+        "Breadcrumb",
+        "PageTitle with actions",
+        "Stat cards row",
+        "Filters",
+        "Main insight cards and tables"
+      ]
+    }
+  ],
+  workflow: [
+    "Collect the screen brief before coding. Do not invent sidebar items, route urls, filters, fields, or table columns if the brief is missing.",
+    "Use Sidebar plus Breadcrumb and PageTitle to lock the shell before building the page body.",
+    "Choose only canonical root exports from @lucasvu/scope-ui.",
+    "Use Card and ui-grid utilities to create the frame first, then place controls and data components inside.",
+    "Keep all palette, radius, surface, and shadow decisions in the shared ui-theme.css preset file.",
+    "End with a consistency check against the selected preset and the screen brief."
+  ],
+  briefFields: uiScreenBriefFields
+};
+
 // src/theme-contract.ts
 var uiThemePresets = [
   {
@@ -7215,4 +7423,4 @@ var uiProjectAiRules = [
   "Prefer root exports and avoid MainFe unless the task explicitly targets a legacy screen."
 ];
 
-export { Alert, ArgonSidebar, AsyncCombobox, Badge, Breadcrumb, Button, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Combobox, FormControl as Control, DataTable, FormDescription as Description, FormField as Field, Form, FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage, Input, FormItem as Item, FormLabel as Label, LineClampTooltip, Loading, main_fe_exports as MainFe, FormMessage as Message, MultiSelect, NumericInput, OverflowTooltip, PageTitle, Pagination, SearchableSelect, SectionTitle, Select, Sidebar, SidebarItem, Stat, Table, TableBody, TableCell, TableHeader, TableRow, Tabs, Textarea, Tooltip, TruncatedText, cn, defaultPermissionChecker, filterSidebarItems, hasActiveDescendant, uiAiManifest, uiDefaultThemePreset, uiProjectAiRules, uiThemeContract, uiThemePresets };
+export { Alert, ArgonSidebar, AsyncCombobox, Badge, Breadcrumb, Button, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Combobox, FormControl as Control, DataTable, FormDescription as Description, FormField as Field, Form, FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage, Input, FormItem as Item, FormLabel as Label, LineClampTooltip, Loading, main_fe_exports as MainFe, FormMessage as Message, MultiSelect, NumericInput, OverflowTooltip, PageTitle, Pagination, SearchableSelect, SectionTitle, Select, Sidebar, SidebarItem, Stat, Table, TableBody, TableCell, TableHeader, TableRow, Tabs, Textarea, Tooltip, TruncatedText, cn, defaultPermissionChecker, filterSidebarItems, hasActiveDescendant, uiAiManifest, uiDefaultThemePreset, uiProjectAiRules, uiScreenBlueprint, uiScreenBriefFields, uiThemeContract, uiThemePresets };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lucasvu/scope-ui",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",