@lucasvu/scope-ui 0.0.7 → 0.1.0

package/AI_SETUP.md

@@ -17,7 +17,7 @@ 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. `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`.
+CLI này sẽ tạo `AGENTS.md`, `src/styles/ui-theme.css`, và `src/layout-presets/workspace-admin-v1.ts` theo đúng convention bên dưới. `AGENTS.md` giờ khóa luôn flow hỏi input -> đọc layout preset -> dựng shell -> mới tới page body. Nếu không truyền `--theme`, preset mặc định là `ocean`.
 
 ## 1. Import style đúng thứ tự
 
@@ -43,7 +43,9 @@ npx scope-ui-init --theme graphite
 
 File generate ra sẽ là source of truth cho palette, surface, radius và shadow của project. Agent phải bám vào file này thay vì tự nghĩ màu mới.
 
-`AGENTS.md` sẽ có thêm block brief dạng YAML để agent điền các giá trị như `routeUrl`, `sidebarItems`, `pageTitle`, `filters`, `fields`, `tableColumns` trước khi bắt đầu viết JSX.
+`AGENTS.md` sẽ có thêm shell brief + screen brief dạng YAML để agent điền các giá trị như `workspaceLabel`, `pageTabs`, `searchPlaceholder`, `routeUrl`, `sidebarItems`, `pageTitle`, `filters`, `fields`, `tableColumns` trước khi bắt đầu viết JSX.
+
+`src/layout-presets/workspace-admin-v1.ts` là source of truth cho shared shell: dark sidebar, gradient topbar, intro card, optional segmented tabs, toolbar card, rồi mới tới body card/table/form.
 
 ```css
 :root {
@@ -63,6 +65,8 @@ File generate ra sẽ là source of truth cho palette, surface, radius và shado
 
 Không nên override màu trực tiếp trong từng component nếu chỉ đang đổi theme.
 
+`src/layout-presets/workspace-admin-v1.ts` không cần import vào runtime. Đây là layout contract cho agent/codegen đọc để giữ dark sidebar, gradient topbar, intro card, tab row, và toolbar card nhất quán giữa các màn.
+
 ## 3. Rule cho AI của project
 
 Copy phần này vào system prompt, repo instructions, `AGENTS.md`, Cursor rules, hoặc bất kỳ chỗ nào project đang dùng để ép AI theo convention:
@@ -75,14 +79,16 @@ 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`
+- read `src/layout-presets/workspace-admin-v1.ts` before changing the app shell or page frame
 - 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
+- fill the shell + screen brief first: `workspaceLabel`, `pageTabs`, `searchPlaceholder`, `routeUrl`, `sidebarItems`, `activeSidebarItemId`, `pageTitle`, `actions`, and the page-specific schema
 - read `uiAiManifest` to choose the right component by intent
 - 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
 - invent a second palette outside the preset file
+- replace the shared dark-sidebar + gradient-topbar shell unless the task explicitly asks for a new shell
 - hardcode brand colors inside page components when a theme token already exists
 - create duplicate Button/Input/Select wrappers unless a project-specific behavior is required
 
@@ -107,7 +113,7 @@ import { uiAiManifest, uiScreenBlueprint, uiThemeContract, uiThemePresets, uiPro
 ```
 
 - `uiAiManifest`: chọn component theo intent
-- `uiScreenBlueprint`: brief input và khung layout chuẩn cho `list | form | detail | dashboard`
+- `uiScreenBlueprint`: brief input và khung layout chuẩn cho `list | form | detail | dashboard`, gồm cả shell fields như `layoutPreset`, `workspaceLabel`, `pageTabs`, `searchPlaceholder`
 - `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
@@ -118,6 +124,7 @@ Nếu project có app shell:
 
 - import `@lucasvu/scope-ui/styles.css` ở app entry
 - import `src/styles/ui-theme.css` ngay sau đó
+- để agent đọc `src/layout-presets/workspace-admin-v1.ts` trước khi build page shell
 - toggle dark mode bằng class `.dark` trên `html` hoặc `body`, hoặc dùng `[data-ui-theme='dark']`
 
 Nếu project có nhiều brand/theme:

package/README.md

@@ -16,7 +16,7 @@ npm install @lucasvu/scope-ui
 import '@lucasvu/scope-ui/styles.css';
 ```
 
-3. Nếu muốn bootstrap rule/theme cho AI trong project consumer:
+3. Nếu muốn bootstrap rule/theme/layout cho AI trong project consumer:
 
 ```bash
 npm install @lucasvu/scope-ui
@@ -31,7 +31,7 @@ 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.
+Lệnh này sẽ tạo `AGENTS.md`, `src/styles/ui-theme.css`, và `src/layout-presets/workspace-admin-v1.ts` trong repo hiện tại theo preset đã chọn. `AGENTS.md` giờ có thêm playbook step-by-step để agent hỏi đủ input, đọc layout preset, rồi 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:
 
@@ -112,10 +112,10 @@ Nếu muốn AI render UI đúng và ổn định theo thư viện này, đừng
 - 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`
+- Chạy `npx scope-ui-init --theme <preset>` ở project consumer sau khi đã cài `@lucasvu/scope-ui` để tạo `AGENTS.md`, `src/styles/ui-theme.css`, và `src/layout-presets/workspace-admin-v1.ts`
 - 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ự: điền brief, 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`
+- Để agent đọc luôn playbook trong `AGENTS.md` và `src/layout-presets/workspace-admin-v1.ts` để đi đúng thứ tự: hỏi input, khóa shell, chọn component, dựng layout, rồi mới tinh chỉnh token
+- Buộc agent điền shell + screen brief trước khi code: `workspaceLabel`, `pageTabs`, `searchPlaceholder`, `routeUrl`, `sidebarItems`, `activeSidebarItemId`, `pageTitle`, `actions`, `filters`, `fields`, `tableColumns`
 - `AGENTS.md` mới sẽ có sẵn block brief dạng YAML để agent hoặc dev điền trực tiếp trước khi code
 - 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
@@ -133,19 +133,19 @@ 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`.
+`uiScreenBlueprint` mô tả input brief bắt buộc cho từng màn hình như `layoutPreset`, `workspaceLabel`, `routeUrl`, `sidebarItems`, `activeSidebarItemId`, `pageTitle`, `pageTabs`, `searchPlaceholder`, `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.
 
-`AI_SETUP.md` và CLI `scope-ui-init` giúp bootstrap rule/theme cho repo consumer mà không cần copy tay.
+`AI_SETUP.md` và CLI `scope-ui-init` giúp bootstrap rule/theme/layout cho repo consumer mà không cần copy tay.
 
 ## Theme Override
 
 Nên để toàn bộ override theme của project vào một file riêng, ví dụ `src/styles/ui-theme.css`, rồi import file này sau `@lucasvu/scope-ui/styles.css`.
 
-Cách nhanh nhất là generate file này từ preset:
+Cách nhanh nhất là generate bộ file này từ preset:
 
 ```bash
 npm install @lucasvu/scope-ui
@@ -158,6 +158,8 @@ import '@lucasvu/scope-ui/styles.css';
 import './styles/ui-theme.css';
 ```
 
+`src/layout-presets/workspace-admin-v1.ts` không cần import ở runtime. File này dùng để agent/codegen đọc và giữ shell layout ổn định giữa các màn.
+
 Ví dụ:
 
 ```css

package/bin/scope-ui-init.mjs

@@ -6,6 +6,44 @@ import process from 'node:process'
 
 const PACKAGE_NAME = '@lucasvu/scope-ui'
 const DEFAULT_THEME_PRESET = 'ocean'
+const DEFAULT_LAYOUT_FILE = 'src/layout-presets/workspace-admin-v1.ts'
+
+const LAYOUT_PRESET = {
+  id: 'workspace-admin-v1',
+  label: 'Workspace Admin v1',
+  description:
+    'Shared admin shell with a dark sidebar, gradient topbar, soft intro card, optional segmented tabs, and card-based content blocks inspired by the Campaigns screen.',
+  recommendedFor: [
+    'Admin workspaces',
+    'Operations dashboards',
+    'CRUD-heavy backoffice screens that should share one shell',
+  ],
+  shellRecipe: [
+    'Dark left sidebar with icon + label navigation and one active item',
+    'Gradient workspace topbar with workspace label on the left and timezone/user slots on the right',
+    'Large page intro card with breadcrumb, title, and optional subtitle',
+    'Optional segmented tabs row directly under the intro card',
+    'Toolbar card with search/filters on the left and actions on the right',
+    'Main body rendered as one or more content cards instead of a flat page',
+  ],
+  requiredFields: [
+    'layoutPreset',
+    'workspaceLabel',
+    'pageKind',
+    'routeUrl',
+    'sidebarItems',
+    'activeSidebarItemId',
+    'pageTitle',
+  ],
+  askBeforeCoding: [
+    'What workspace label should appear in the topbar?',
+    'What timezone or top-right meta label should appear beside the user badge?',
+    'What sidebar items exist and which one is active on this screen?',
+    'Does this screen need segmented tabs? If yes, what are the tab labels and which tab is active?',
+    'What search placeholder, filters, and primary action belong in the toolbar card?',
+    'What columns, fields, or summary blocks should be rendered in the page body?',
+  ],
+}
 
 const THEME_PRESETS = {
   ocean: {
@@ -216,6 +254,7 @@ function parseArgs(argv) {
     force: false,
     agentsFile: 'AGENTS.md',
     themeFile: 'src/styles/ui-theme.css',
+    layoutFile: DEFAULT_LAYOUT_FILE,
     theme: DEFAULT_THEME_PRESET,
     listThemes: false,
   }
@@ -248,6 +287,16 @@ function parseArgs(argv) {
       continue
     }
 
+    if (arg === '--layout-file') {
+      const value = argv[index + 1]
+      if (!value || value.startsWith('--')) {
+        exitWithMissingValue('--layout-file')
+      }
+      args.layoutFile = value
+      index += 1
+      continue
+    }
+
     if (arg === '--theme') {
       const value = argv[index + 1]
       if (!value || value.startsWith('--')) {
@@ -288,12 +337,13 @@ Usage:
     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
+  npx scope-ui-init --agents-file AGENTS.md --theme-file src/styles/ui-theme.css --layout-file ${DEFAULT_LAYOUT_FILE}
 
 Options:
   --force        overwrite existing files
   --agents-file  target path for the generated AGENTS.md file
   --theme-file   target path for the generated theme override file
+  --layout-file  target path for the generated layout preset file
   --theme        theme preset id (${Object.keys(THEME_PRESETS).join(', ')})
   --list-themes  show the approved preset list
   --help, -h     show this help
@@ -333,38 +383,72 @@ function renderTokenBlock(tokens) {
     .join('\n')
 }
 
-function createAgentsTemplate({ themeFile, themePreset }) {
+function renderMarkdownList(items) {
+  return items.map((item) => `- ${item}`).join('\n')
+}
+
+function createAgentsTemplate({ themeFile, layoutFile, themePreset, layoutPreset }) {
   return `# Agent Rules
 
 This repo uses \`${PACKAGE_NAME}\` as the default UI library.
 This repo is locked to the \`${themePreset.label}\` theme preset (\`${themePreset.id}\`).
+This repo uses the \`${layoutPreset.label}\` shell preset (\`${layoutPreset.id}\`) as the shared layout baseline.
 
 Primary references:
 - \`node_modules/${PACKAGE_NAME}/README.md\`
 - \`node_modules/${PACKAGE_NAME}/AI_SETUP.md\`
 - \`uiScreenBlueprint\` and \`uiAiManifest\` from \`${PACKAGE_NAME}\`
 - \`${themeFile}\`
+- \`${layoutFile}\`
 
 Theme preset summary:
 - ${themePreset.description}
 - Recommended for: ${themePreset.recommendedFor.join(', ')}
 
+Layout preset summary:
+${renderMarkdownList(layoutPreset.shellRecipe)}
+
 ## Required Flow
 
 When asked to build or edit a screen, follow these steps in order:
 
-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.
+1. Read \`${themeFile}\`, \`${layoutFile}\`, \`node_modules/${PACKAGE_NAME}/README.md\`, \`node_modules/${PACKAGE_NAME}/AI_SETUP.md\`, and the exported \`uiScreenBlueprint\` contract before generating UI.
+2. Fill the shell brief and screen brief first. If a required field is missing, stop and ask for that exact value before writing JSX. Only leave TODO placeholders when the user explicitly asks for an incomplete scaffold.
 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 exact 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 cards/tables.
-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, run the output checklist in this file.
+4. Treat \`${layoutFile}\` as the source of truth for the app shell. Keep the dark sidebar, gradient topbar, intro card, and card-based body structure aligned with that preset unless the user explicitly asks for a different shell.
+5. Identify the page kind (\`list | form | detail | dashboard\`), then map each block to canonical components from \`uiAiManifest\` before writing JSX.
+6. Build the shell in this exact order: \`Sidebar\` -> workspace topbar -> intro card (\`Breadcrumb\` + \`PageTitle\`) -> optional segmented tabs -> toolbar card -> page body cards/grids.
+7. For list pages, build the toolbar card first and then the \`DataTable\`. For form pages, keep the same shell and swap the body into section cards and a bottom action row. For detail pages, keep the shell and render summary/detail cards plus related tables. For dashboard pages, keep the shell and render stat cards plus supporting cards/tables.
+8. If \`${layoutFile}\` says a slot is optional, omit it cleanly when the brief does not request it. Do not invent tabs, workspace labels, filters, or toolbar actions.
+9. 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.
+10. Before finishing, run the output checklist in this file.
+
+## Ask For Missing Input
+
+If any of these are missing, ask the user directly before writing JSX:
+
+${renderMarkdownList(layoutPreset.askBeforeCoding)}
+
+## Shell Brief
+
+Complete this shell brief before writing JSX:
+
+\`\`\`yaml
+layoutPreset: ${layoutPreset.id}
+workspaceLabel:
+timezoneLabel:
+userBadgeLabel:
+pageTabs:
+  - value:
+    label:
+activePageTab:
+searchPlaceholder:
+toolbarNote:
+\`\`\`
 
 ## Screen Brief
 
-Complete this brief before writing JSX:
+Complete this screen brief before writing JSX:
 
 \`\`\`yaml
 pageKind: list | form | detail | dashboard
@@ -373,6 +457,7 @@ sidebarItems:
   - id:
     title:
     href:
+    icon:
 activeSidebarItemId:
 breadcrumbs:
   - label:
@@ -421,12 +506,18 @@ emptyState:
 permissions: []
 \`\`\`
 
+## Shell Lock
+
+Keep the layout aligned with \`${layoutPreset.id}\`:
+
+${renderMarkdownList(layoutPreset.shellRecipe)}
+
 ## Page Frame Recipes
 
-- \`list\`: \`Sidebar\` -> \`Breadcrumb\` -> \`PageTitle\` -> header actions -> optional stats -> filter \`Card\` -> \`DataTable\` \`Card\`
-- \`form\`: \`Sidebar\` -> \`Breadcrumb\` -> \`PageTitle\` -> primary/cancel actions -> sectioned form \`Card\` blocks -> bottom action row
-- \`detail\`: \`Sidebar\` -> \`Breadcrumb\` -> \`PageTitle\` -> status/actions -> summary metadata \`Card\` -> detail \`Card\` blocks -> related \`DataTable\`
-- \`dashboard\`: \`Sidebar\` -> \`Breadcrumb\` -> \`PageTitle\` -> header actions -> \`Stat\` row -> filters -> insight \`Card\` blocks and \`DataTable\`
+- \`list\`: dark \`Sidebar\` -> workspace topbar -> intro card -> optional segmented tabs -> toolbar \`Card\` -> \`DataTable\` \`Card\`
+- \`form\`: dark \`Sidebar\` -> workspace topbar -> intro card -> optional segmented tabs -> top actions -> sectioned form \`Card\` blocks -> bottom action row
+- \`detail\`: dark \`Sidebar\` -> workspace topbar -> intro card -> optional segmented tabs -> status/actions -> summary metadata \`Card\` -> detail \`Card\` blocks -> related \`DataTable\`
+- \`dashboard\`: dark \`Sidebar\` -> workspace topbar -> intro card -> optional segmented tabs -> toolbar \`Card\` -> \`Stat\` row -> insight \`Card\` blocks and \`DataTable\`
 
 ## Hard Rules
 
@@ -434,6 +525,7 @@ permissions: []
 - import the project theme override file after the package stylesheet
 - use root exports from \`${PACKAGE_NAME}\`
 - use \`${themeFile}\` as the only source of truth for colors, radius, surfaces, and shadows
+- use \`${layoutFile}\` as the source of truth for the shell layout and shared page frame
 - keep layouts and component choices aligned with the shared preset-driven UI used across projects
 - read \`uiAiManifest\` before choosing components
 - read \`uiThemeContract\` before changing colors, surfaces, borders, radius, or shadows
@@ -442,6 +534,7 @@ permissions: []
 Do not:
 - import from \`MainFe\` unless the task explicitly targets a legacy screen
 - invent a second palette or one-off brand colors outside \`${themeFile}\`
+- replace the shared dark-sidebar + gradient-topbar shell with a flat blank layout unless the user explicitly requests it
 - restyle individual pages if the preset tokens can solve it globally
 - create duplicate Button/Input/Select wrappers unless a project-specific behavior is required
 
@@ -461,13 +554,15 @@ Do not:
 
 Before finishing, confirm all of these are true:
 
-- The screen brief is complete or unresolved values are clearly marked as TODO.
-- The shell contains \`Sidebar\`, \`Breadcrumb\`, and \`PageTitle\` in the correct order.
+- The shell brief and screen brief are complete.
+- Any missing required input was explicitly asked for before coding.
+- The shell matches \`${layoutPreset.id}\` with a dark sidebar, gradient topbar, intro card, and card-based body structure.
 - The chosen components match the page kind and the brief.
 - No \`MainFe\` imports were used.
 - No hardcoded brand colors were added in page components.
 - Theme decisions live in \`${themeFile}\`, not in ad hoc JSX styling.
 - Spacing, card structure, and actions are consistent with the shared preset.
+- The layout shell stayed stable even if the page body changed.
 `
 }
 
@@ -487,6 +582,90 @@ ${renderTokenBlock(themePreset.tokens.dark)}
 `
 }
 
+function createLayoutTemplate({ themeFile, layoutPreset }) {
+  return `/* Generated by scope-ui-init. */
+/* Layout preset: ${layoutPreset.label} (${layoutPreset.id}) */
+/* Use this file as the shared app-shell source of truth for AI/codegen. */
+
+export const uiLayoutPreset = {
+  id: '${layoutPreset.id}',
+  label: '${layoutPreset.label}',
+  description:
+    '${layoutPreset.description}',
+  themeSource: '${themeFile}',
+  recommendedFor: [
+${layoutPreset.recommendedFor.map((item) => `    '${item}',`).join('\n')}
+  ],
+  shellRecipe: [
+${layoutPreset.shellRecipe.map((item) => `    '${item}',`).join('\n')}
+  ],
+  requiredFields: [
+${layoutPreset.requiredFields.map((item) => `    '${item}',`).join('\n')}
+  ],
+  askBeforeCoding: [
+${layoutPreset.askBeforeCoding.map((item) => `    '${item}',`).join('\n')}
+  ],
+  shell: {
+    sidebar: {
+      tone: 'dark',
+      width: '240px',
+      content: ['workspace badge', 'icon + label navigation', 'active state'],
+    },
+    topbar: {
+      background: 'theme gradient from --primary-grad-from to --primary-grad-to',
+      leftSlot: 'workspaceLabel',
+      rightSlots: ['timezoneLabel', 'userBadgeLabel'],
+    },
+    introCard: {
+      content: ['breadcrumbs', 'pageTitle', 'pageSubtitle'],
+      surface: 'soft elevated card',
+    },
+    pageTabs: {
+      optional: true,
+      style: 'segmented pills',
+      fields: ['pageTabs', 'activePageTab'],
+    },
+    toolbarCard: {
+      optional: true,
+      leftSlots: ['searchPlaceholder', 'filters'],
+      rightSlots: ['secondaryActions', 'primaryAction'],
+    },
+  },
+  pageBodies: {
+    list: ['toolbar card', 'DataTable card', 'rowActions', 'emptyState'],
+    form: ['sectioned form cards', 'fields', 'bottom action row'],
+    detail: ['summary metadata card', 'detailSections', 'related tables'],
+    dashboard: ['summaryStats', 'filters', 'insight cards', 'DataTable'],
+  },
+  hardRules: [
+    'Keep the dark sidebar and gradient topbar shell stable across screens.',
+    'Do not replace the intro card with a bare page title row.',
+    'Use the shared theme tokens from the themeSource file for color, border, surface, and shadow decisions.',
+    'Only omit tabs or toolbar sections when the brief explicitly leaves them out.',
+    'Ask for missing required fields before generating JSX instead of guessing from the screenshot.',
+  ],
+  exampleBrief: {
+    layoutPreset: '${layoutPreset.id}',
+    workspaceLabel: 'Workspace',
+    timezoneLabel: 'UTC+07:00',
+    userBadgeLabel: 'L',
+    pageKind: 'list',
+    routeUrl: '/campaigns/new',
+    activeSidebarItemId: 'campaigns',
+    pageTabs: [
+      { value: 'overview', label: 'Overview' },
+      { value: 'coupons', label: 'Coupons' },
+      { value: 'redemption', label: 'Redemption' },
+    ],
+    activePageTab: 'coupons',
+    searchPlaceholder: 'Search by coupon code',
+  },
+} as const
+
+export type UiLayoutPreset = typeof uiLayoutPreset
+`
+}
+
 function writeFile(targetPath, content, force) {
   const absolutePath = resolve(process.cwd(), targetPath)
   const alreadyExists = existsSync(absolutePath)
@@ -511,7 +690,12 @@ const themePreset = resolveThemePreset(options.theme)
 
 const agentsResult = writeFile(
   options.agentsFile,
-  createAgentsTemplate({ themeFile: options.themeFile, themePreset }),
+  createAgentsTemplate({
+    themeFile: options.themeFile,
+    layoutFile: options.layoutFile,
+    themePreset,
+    layoutPreset: LAYOUT_PRESET,
+  }),
   options.force,
 )
 
@@ -521,13 +705,21 @@ const themeResult = writeFile(
   options.force,
 )
 
+const layoutResult = writeFile(
+  options.layoutFile,
+  createLayoutTemplate({ themeFile: options.themeFile, layoutPreset: LAYOUT_PRESET }),
+  options.force,
+)
+
 console.log(`Initialized ${PACKAGE_NAME}`)
 console.log(`- theme preset: ${themePreset.label} (${themePreset.id})`)
+console.log(`- layout preset: ${LAYOUT_PRESET.label} (${LAYOUT_PRESET.id})`)
 console.log(`- ${agentsResult.path}: ${agentsResult.status}`)
 console.log(`- ${themeResult.path}: ${themeResult.status}`)
+console.log(`- ${layoutResult.path}: ${layoutResult.status}`)
 console.log('')
 console.log('Next steps:')
 console.log(`1. Import \`${PACKAGE_NAME}/styles.css\` once at your app entry.`)
 console.log(`2. Import \`${options.themeFile}\` right after the package stylesheet.`)
-console.log(`3. Let your agent read \`${options.agentsFile}\` before generating UI.`)
+console.log(`3. Let your agent read \`${options.agentsFile}\` and \`${options.layoutFile}\` before generating UI.`)
 console.log(`4. Re-run this command with \`--theme <preset> --force\` if you want another approved preset.`)

package/dist/index.cjs

@@ -6647,7 +6647,8 @@ 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.",
+    "Collect the shell + screen brief first: layout preset, workspace label, route url, sidebar items, active sidebar item, page title, tabs/actions, and the page-specific content schema.",
+    "If the project ships a generated layout preset file, keep the shell aligned with it instead of inventing a new page frame.",
     "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.",
@@ -6865,6 +6866,30 @@ var uiAiManifest = {
 
 // src/screen-blueprint.ts
 var uiScreenBriefFields = [
+  {
+    id: "layoutPreset",
+    label: "Layout preset",
+    description: "Shared shell preset id that locks the sidebar/topbar/page-card structure.",
+    required: false,
+    appliesTo: ["all"],
+    example: "workspace-admin-v1"
+  },
+  {
+    id: "workspaceLabel",
+    label: "Workspace label",
+    description: "Short label shown in the sidebar or workspace topbar.",
+    required: false,
+    appliesTo: ["all"],
+    example: "Workspace"
+  },
+  {
+    id: "timezoneLabel",
+    label: "Timezone/meta label",
+    description: "Short meta label shown in the top-right shell area, such as a timezone or environment.",
+    required: false,
+    appliesTo: ["all"],
+    example: "UTC+07:00"
+  },
   {
     id: "pageKind",
     label: "Page kind",
@@ -6921,6 +6946,22 @@ var uiScreenBriefFields = [
     appliesTo: ["all"],
     example: "Manage internal user accounts and permissions."
   },
+  {
+    id: "pageTabs",
+    label: "Page tabs",
+    description: "Optional segmented tabs rendered under the intro card.",
+    required: false,
+    appliesTo: ["all"],
+    example: '[{ value: "overview", label: "Overview" }, { value: "coupons", label: "Coupons" }]'
+  },
+  {
+    id: "activePageTab",
+    label: "Active page tab",
+    description: "The selected segmented tab value when tabs are present.",
+    required: false,
+    appliesTo: ["all"],
+    example: "coupons"
+  },
   {
     id: "primaryAction",
     label: "Primary action",
@@ -6953,6 +6994,14 @@ var uiScreenBriefFields = [
     appliesTo: ["list", "dashboard"],
     example: '[{ type: "search", label: "Search user" }, { type: "select", label: "Role" }]'
   },
+  {
+    id: "searchPlaceholder",
+    label: "Search placeholder",
+    description: "Placeholder text for the main toolbar search input when the shell includes one.",
+    required: false,
+    appliesTo: ["list", "dashboard"],
+    example: "Search by coupon code"
+  },
   {
     id: "tableColumns",
     label: "Table columns",
@@ -7017,10 +7066,11 @@ var uiScreenBlueprint = {
       label: "List page",
       frame: [
         "Sidebar shell",
-        "Breadcrumb",
-        "PageTitle with actions",
+        "Workspace topbar",
+        "Page intro card with Breadcrumb and PageTitle",
+        "Optional segmented tabs",
+        "Toolbar card",
         "Optional stats",
-        "Filter card",
         "DataTable card"
       ]
     },
@@ -7029,8 +7079,10 @@ var uiScreenBlueprint = {
       label: "Form page",
       frame: [
         "Sidebar shell",
-        "Breadcrumb",
-        "PageTitle with primary and cancel actions",
+        "Workspace topbar",
+        "Page intro card with Breadcrumb and PageTitle",
+        "Optional segmented tabs",
+        "Header actions",
         "Sectioned form cards",
         "Bottom action row"
       ]
@@ -7040,7 +7092,9 @@ var uiScreenBlueprint = {
       label: "Detail page",
       frame: [
         "Sidebar shell",
-        "Breadcrumb",
+        "Workspace topbar",
+        "Page intro card with Breadcrumb and PageTitle",
+        "Optional segmented tabs",
         "PageTitle with status/actions",
         "Summary stats or metadata card",
         "Detail cards and related tables"
@@ -7051,17 +7105,18 @@ var uiScreenBlueprint = {
       label: "Dashboard page",
       frame: [
         "Sidebar shell",
-        "Breadcrumb",
-        "PageTitle with actions",
+        "Workspace topbar",
+        "Page intro card with Breadcrumb and PageTitle",
+        "Optional segmented tabs",
+        "Toolbar card 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.",
+    "Collect the shell + screen brief before coding. Do not invent layout presets, workspace labels, sidebar items, route urls, tabs, filters, fields, or table columns if the brief is missing.",
+    "Use Sidebar plus the workspace topbar and intro card 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.",

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.", "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 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 shell + screen brief first: layout preset, workspace label, route url, sidebar items, active sidebar item, page title, tabs/actions, and the page-specific content schema.", "If the project ships a generated layout preset file, keep the shell aligned with it instead of inventing a new page frame.", "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;
@@ -921,6 +921,27 @@ type UiScreenBriefField = {
     example: string;
 };
 declare const uiScreenBriefFields: readonly [{
+    readonly id: "layoutPreset";
+    readonly label: "Layout preset";
+    readonly description: "Shared shell preset id that locks the sidebar/topbar/page-card structure.";
+    readonly required: false;
+    readonly appliesTo: ["all"];
+    readonly example: "workspace-admin-v1";
+}, {
+    readonly id: "workspaceLabel";
+    readonly label: "Workspace label";
+    readonly description: "Short label shown in the sidebar or workspace topbar.";
+    readonly required: false;
+    readonly appliesTo: ["all"];
+    readonly example: "Workspace";
+}, {
+    readonly id: "timezoneLabel";
+    readonly label: "Timezone/meta label";
+    readonly description: "Short meta label shown in the top-right shell area, such as a timezone or environment.";
+    readonly required: false;
+    readonly appliesTo: ["all"];
+    readonly example: "UTC+07:00";
+}, {
     readonly id: "pageKind";
     readonly label: "Page kind";
     readonly description: "Choose the base recipe for the screen.";
@@ -969,6 +990,20 @@ declare const uiScreenBriefFields: readonly [{
     readonly required: false;
     readonly appliesTo: ["all"];
     readonly example: "Manage internal user accounts and permissions.";
+}, {
+    readonly id: "pageTabs";
+    readonly label: "Page tabs";
+    readonly description: "Optional segmented tabs rendered under the intro card.";
+    readonly required: false;
+    readonly appliesTo: ["all"];
+    readonly example: "[{ value: \"overview\", label: \"Overview\" }, { value: \"coupons\", label: \"Coupons\" }]";
+}, {
+    readonly id: "activePageTab";
+    readonly label: "Active page tab";
+    readonly description: "The selected segmented tab value when tabs are present.";
+    readonly required: false;
+    readonly appliesTo: ["all"];
+    readonly example: "coupons";
 }, {
     readonly id: "primaryAction";
     readonly label: "Primary action";
@@ -997,6 +1032,13 @@ declare const uiScreenBriefFields: readonly [{
     readonly required: false;
     readonly appliesTo: ["list", "dashboard"];
     readonly example: "[{ type: \"search\", label: \"Search user\" }, { type: \"select\", label: \"Role\" }]";
+}, {
+    readonly id: "searchPlaceholder";
+    readonly label: "Search placeholder";
+    readonly description: "Placeholder text for the main toolbar search input when the shell includes one.";
+    readonly required: false;
+    readonly appliesTo: ["list", "dashboard"];
+    readonly example: "Search by coupon code";
 }, {
     readonly id: "tableColumns";
     readonly label: "Table columns";
@@ -1051,22 +1093,43 @@ 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 frame: readonly ["Sidebar shell", "Workspace topbar", "Page intro card with Breadcrumb and PageTitle", "Optional segmented tabs", "Toolbar card", "Optional stats", "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 frame: readonly ["Sidebar shell", "Workspace topbar", "Page intro card with Breadcrumb and PageTitle", "Optional segmented tabs", "Header 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 frame: readonly ["Sidebar shell", "Workspace topbar", "Page intro card with Breadcrumb and PageTitle", "Optional segmented tabs", "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 frame: readonly ["Sidebar shell", "Workspace topbar", "Page intro card with Breadcrumb and PageTitle", "Optional segmented tabs", "Toolbar card with actions", "Stat cards row", "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 workflow: readonly ["Collect the shell + screen brief before coding. Do not invent layout presets, workspace labels, sidebar items, route urls, tabs, filters, fields, or table columns if the brief is missing.", "Use Sidebar plus the workspace topbar and intro card 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: "layoutPreset";
+        readonly label: "Layout preset";
+        readonly description: "Shared shell preset id that locks the sidebar/topbar/page-card structure.";
+        readonly required: false;
+        readonly appliesTo: ["all"];
+        readonly example: "workspace-admin-v1";
+    }, {
+        readonly id: "workspaceLabel";
+        readonly label: "Workspace label";
+        readonly description: "Short label shown in the sidebar or workspace topbar.";
+        readonly required: false;
+        readonly appliesTo: ["all"];
+        readonly example: "Workspace";
+    }, {
+        readonly id: "timezoneLabel";
+        readonly label: "Timezone/meta label";
+        readonly description: "Short meta label shown in the top-right shell area, such as a timezone or environment.";
+        readonly required: false;
+        readonly appliesTo: ["all"];
+        readonly example: "UTC+07:00";
+    }, {
         readonly id: "pageKind";
         readonly label: "Page kind";
         readonly description: "Choose the base recipe for the screen.";
@@ -1115,6 +1178,20 @@ declare const uiScreenBlueprint: {
         readonly required: false;
         readonly appliesTo: ["all"];
         readonly example: "Manage internal user accounts and permissions.";
+    }, {
+        readonly id: "pageTabs";
+        readonly label: "Page tabs";
+        readonly description: "Optional segmented tabs rendered under the intro card.";
+        readonly required: false;
+        readonly appliesTo: ["all"];
+        readonly example: "[{ value: \"overview\", label: \"Overview\" }, { value: \"coupons\", label: \"Coupons\" }]";
+    }, {
+        readonly id: "activePageTab";
+        readonly label: "Active page tab";
+        readonly description: "The selected segmented tab value when tabs are present.";
+        readonly required: false;
+        readonly appliesTo: ["all"];
+        readonly example: "coupons";
     }, {
         readonly id: "primaryAction";
         readonly label: "Primary action";
@@ -1143,6 +1220,13 @@ declare const uiScreenBlueprint: {
         readonly required: false;
         readonly appliesTo: ["list", "dashboard"];
         readonly example: "[{ type: \"search\", label: \"Search user\" }, { type: \"select\", label: \"Role\" }]";
+    }, {
+        readonly id: "searchPlaceholder";
+        readonly label: "Search placeholder";
+        readonly description: "Placeholder text for the main toolbar search input when the shell includes one.";
+        readonly required: false;
+        readonly appliesTo: ["list", "dashboard"];
+        readonly example: "Search by coupon code";
     }, {
         readonly id: "tableColumns";
         readonly label: "Table columns";

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.", "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 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 shell + screen brief first: layout preset, workspace label, route url, sidebar items, active sidebar item, page title, tabs/actions, and the page-specific content schema.", "If the project ships a generated layout preset file, keep the shell aligned with it instead of inventing a new page frame.", "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;
@@ -921,6 +921,27 @@ type UiScreenBriefField = {
     example: string;
 };
 declare const uiScreenBriefFields: readonly [{
+    readonly id: "layoutPreset";
+    readonly label: "Layout preset";
+    readonly description: "Shared shell preset id that locks the sidebar/topbar/page-card structure.";
+    readonly required: false;
+    readonly appliesTo: ["all"];
+    readonly example: "workspace-admin-v1";
+}, {
+    readonly id: "workspaceLabel";
+    readonly label: "Workspace label";
+    readonly description: "Short label shown in the sidebar or workspace topbar.";
+    readonly required: false;
+    readonly appliesTo: ["all"];
+    readonly example: "Workspace";
+}, {
+    readonly id: "timezoneLabel";
+    readonly label: "Timezone/meta label";
+    readonly description: "Short meta label shown in the top-right shell area, such as a timezone or environment.";
+    readonly required: false;
+    readonly appliesTo: ["all"];
+    readonly example: "UTC+07:00";
+}, {
     readonly id: "pageKind";
     readonly label: "Page kind";
     readonly description: "Choose the base recipe for the screen.";
@@ -969,6 +990,20 @@ declare const uiScreenBriefFields: readonly [{
     readonly required: false;
     readonly appliesTo: ["all"];
     readonly example: "Manage internal user accounts and permissions.";
+}, {
+    readonly id: "pageTabs";
+    readonly label: "Page tabs";
+    readonly description: "Optional segmented tabs rendered under the intro card.";
+    readonly required: false;
+    readonly appliesTo: ["all"];
+    readonly example: "[{ value: \"overview\", label: \"Overview\" }, { value: \"coupons\", label: \"Coupons\" }]";
+}, {
+    readonly id: "activePageTab";
+    readonly label: "Active page tab";
+    readonly description: "The selected segmented tab value when tabs are present.";
+    readonly required: false;
+    readonly appliesTo: ["all"];
+    readonly example: "coupons";
 }, {
     readonly id: "primaryAction";
     readonly label: "Primary action";
@@ -997,6 +1032,13 @@ declare const uiScreenBriefFields: readonly [{
     readonly required: false;
     readonly appliesTo: ["list", "dashboard"];
     readonly example: "[{ type: \"search\", label: \"Search user\" }, { type: \"select\", label: \"Role\" }]";
+}, {
+    readonly id: "searchPlaceholder";
+    readonly label: "Search placeholder";
+    readonly description: "Placeholder text for the main toolbar search input when the shell includes one.";
+    readonly required: false;
+    readonly appliesTo: ["list", "dashboard"];
+    readonly example: "Search by coupon code";
 }, {
     readonly id: "tableColumns";
     readonly label: "Table columns";
@@ -1051,22 +1093,43 @@ 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 frame: readonly ["Sidebar shell", "Workspace topbar", "Page intro card with Breadcrumb and PageTitle", "Optional segmented tabs", "Toolbar card", "Optional stats", "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 frame: readonly ["Sidebar shell", "Workspace topbar", "Page intro card with Breadcrumb and PageTitle", "Optional segmented tabs", "Header 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 frame: readonly ["Sidebar shell", "Workspace topbar", "Page intro card with Breadcrumb and PageTitle", "Optional segmented tabs", "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 frame: readonly ["Sidebar shell", "Workspace topbar", "Page intro card with Breadcrumb and PageTitle", "Optional segmented tabs", "Toolbar card with actions", "Stat cards row", "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 workflow: readonly ["Collect the shell + screen brief before coding. Do not invent layout presets, workspace labels, sidebar items, route urls, tabs, filters, fields, or table columns if the brief is missing.", "Use Sidebar plus the workspace topbar and intro card 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: "layoutPreset";
+        readonly label: "Layout preset";
+        readonly description: "Shared shell preset id that locks the sidebar/topbar/page-card structure.";
+        readonly required: false;
+        readonly appliesTo: ["all"];
+        readonly example: "workspace-admin-v1";
+    }, {
+        readonly id: "workspaceLabel";
+        readonly label: "Workspace label";
+        readonly description: "Short label shown in the sidebar or workspace topbar.";
+        readonly required: false;
+        readonly appliesTo: ["all"];
+        readonly example: "Workspace";
+    }, {
+        readonly id: "timezoneLabel";
+        readonly label: "Timezone/meta label";
+        readonly description: "Short meta label shown in the top-right shell area, such as a timezone or environment.";
+        readonly required: false;
+        readonly appliesTo: ["all"];
+        readonly example: "UTC+07:00";
+    }, {
         readonly id: "pageKind";
         readonly label: "Page kind";
         readonly description: "Choose the base recipe for the screen.";
@@ -1115,6 +1178,20 @@ declare const uiScreenBlueprint: {
         readonly required: false;
         readonly appliesTo: ["all"];
         readonly example: "Manage internal user accounts and permissions.";
+    }, {
+        readonly id: "pageTabs";
+        readonly label: "Page tabs";
+        readonly description: "Optional segmented tabs rendered under the intro card.";
+        readonly required: false;
+        readonly appliesTo: ["all"];
+        readonly example: "[{ value: \"overview\", label: \"Overview\" }, { value: \"coupons\", label: \"Coupons\" }]";
+    }, {
+        readonly id: "activePageTab";
+        readonly label: "Active page tab";
+        readonly description: "The selected segmented tab value when tabs are present.";
+        readonly required: false;
+        readonly appliesTo: ["all"];
+        readonly example: "coupons";
     }, {
         readonly id: "primaryAction";
         readonly label: "Primary action";
@@ -1143,6 +1220,13 @@ declare const uiScreenBlueprint: {
         readonly required: false;
         readonly appliesTo: ["list", "dashboard"];
         readonly example: "[{ type: \"search\", label: \"Search user\" }, { type: \"select\", label: \"Role\" }]";
+    }, {
+        readonly id: "searchPlaceholder";
+        readonly label: "Search placeholder";
+        readonly description: "Placeholder text for the main toolbar search input when the shell includes one.";
+        readonly required: false;
+        readonly appliesTo: ["list", "dashboard"];
+        readonly example: "Search by coupon code";
     }, {
         readonly id: "tableColumns";
         readonly label: "Table columns";

package/dist/index.js

@@ -6625,7 +6625,8 @@ 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.",
+    "Collect the shell + screen brief first: layout preset, workspace label, route url, sidebar items, active sidebar item, page title, tabs/actions, and the page-specific content schema.",
+    "If the project ships a generated layout preset file, keep the shell aligned with it instead of inventing a new page frame.",
     "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.",
@@ -6843,6 +6844,30 @@ var uiAiManifest = {
 
 // src/screen-blueprint.ts
 var uiScreenBriefFields = [
+  {
+    id: "layoutPreset",
+    label: "Layout preset",
+    description: "Shared shell preset id that locks the sidebar/topbar/page-card structure.",
+    required: false,
+    appliesTo: ["all"],
+    example: "workspace-admin-v1"
+  },
+  {
+    id: "workspaceLabel",
+    label: "Workspace label",
+    description: "Short label shown in the sidebar or workspace topbar.",
+    required: false,
+    appliesTo: ["all"],
+    example: "Workspace"
+  },
+  {
+    id: "timezoneLabel",
+    label: "Timezone/meta label",
+    description: "Short meta label shown in the top-right shell area, such as a timezone or environment.",
+    required: false,
+    appliesTo: ["all"],
+    example: "UTC+07:00"
+  },
   {
     id: "pageKind",
     label: "Page kind",
@@ -6899,6 +6924,22 @@ var uiScreenBriefFields = [
     appliesTo: ["all"],
     example: "Manage internal user accounts and permissions."
   },
+  {
+    id: "pageTabs",
+    label: "Page tabs",
+    description: "Optional segmented tabs rendered under the intro card.",
+    required: false,
+    appliesTo: ["all"],
+    example: '[{ value: "overview", label: "Overview" }, { value: "coupons", label: "Coupons" }]'
+  },
+  {
+    id: "activePageTab",
+    label: "Active page tab",
+    description: "The selected segmented tab value when tabs are present.",
+    required: false,
+    appliesTo: ["all"],
+    example: "coupons"
+  },
   {
     id: "primaryAction",
     label: "Primary action",
@@ -6931,6 +6972,14 @@ var uiScreenBriefFields = [
     appliesTo: ["list", "dashboard"],
     example: '[{ type: "search", label: "Search user" }, { type: "select", label: "Role" }]'
   },
+  {
+    id: "searchPlaceholder",
+    label: "Search placeholder",
+    description: "Placeholder text for the main toolbar search input when the shell includes one.",
+    required: false,
+    appliesTo: ["list", "dashboard"],
+    example: "Search by coupon code"
+  },
   {
     id: "tableColumns",
     label: "Table columns",
@@ -6995,10 +7044,11 @@ var uiScreenBlueprint = {
       label: "List page",
       frame: [
         "Sidebar shell",
-        "Breadcrumb",
-        "PageTitle with actions",
+        "Workspace topbar",
+        "Page intro card with Breadcrumb and PageTitle",
+        "Optional segmented tabs",
+        "Toolbar card",
         "Optional stats",
-        "Filter card",
         "DataTable card"
       ]
     },
@@ -7007,8 +7057,10 @@ var uiScreenBlueprint = {
       label: "Form page",
       frame: [
         "Sidebar shell",
-        "Breadcrumb",
-        "PageTitle with primary and cancel actions",
+        "Workspace topbar",
+        "Page intro card with Breadcrumb and PageTitle",
+        "Optional segmented tabs",
+        "Header actions",
         "Sectioned form cards",
         "Bottom action row"
       ]
@@ -7018,7 +7070,9 @@ var uiScreenBlueprint = {
       label: "Detail page",
       frame: [
         "Sidebar shell",
-        "Breadcrumb",
+        "Workspace topbar",
+        "Page intro card with Breadcrumb and PageTitle",
+        "Optional segmented tabs",
         "PageTitle with status/actions",
         "Summary stats or metadata card",
         "Detail cards and related tables"
@@ -7029,17 +7083,18 @@ var uiScreenBlueprint = {
       label: "Dashboard page",
       frame: [
         "Sidebar shell",
-        "Breadcrumb",
-        "PageTitle with actions",
+        "Workspace topbar",
+        "Page intro card with Breadcrumb and PageTitle",
+        "Optional segmented tabs",
+        "Toolbar card 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.",
+    "Collect the shell + screen brief before coding. Do not invent layout presets, workspace labels, sidebar items, route urls, tabs, filters, fields, or table columns if the brief is missing.",
+    "Use Sidebar plus the workspace topbar and intro card 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.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lucasvu/scope-ui",
-  "version": "0.0.7",
+  "version": "0.1.0",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -50,7 +50,7 @@
     "autoprefixer": "^10.4.23",
     "postcss": "^8.5.6",
     "tailwindcss": "3.4.17",
-    "tsup": "^8.5.0",
+    "tsup": "^8.5.1",
     "typescript": "^5.8.3"
   }
-}
+}