@lucasvu/scope-ui 0.0.4 → 0.0.6

package/AI_SETUP.md

@@ -5,12 +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
+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:
 
-CLI này sẽ tạo `AGENTS.md` và `src/styles/ui-theme.css` theo đúng convention bên dưới.
+```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. `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ự
 
@@ -23,10 +30,19 @@ import './styles/ui-theme.css'
 
 `ui-theme.css` nên là nơi duy nhất override màu, surface, border, shadow và gradient của thư viện.
 
-## 2. Tạo file theme của project
+## 2. Chọn preset theme của project
 
 Đặt file tại `src/styles/ui-theme.css`.
 
+Dùng `--list-themes` để xem preset được duyệt, rồi generate preset đã chọn:
+
+```bash
+npx scope-ui-init --list-themes
+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.
+
 ```css
 :root {
   --tw-primary: 12 88% 56%;
@@ -56,11 +72,15 @@ Always:
 - import `@lucasvu/scope-ui/styles.css` once at the app entry
 - 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
+- invent a second palette outside the preset file
 - 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
 
@@ -81,11 +101,13 @@ Component choice:
 Trong code, AI có thể đọc trực tiếp:
 
 ```ts
-import { uiAiManifest, uiThemeContract, 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
 
 ## 5. Chỗ override theme
@@ -100,4 +122,5 @@ Nếu project có nhiều brand/theme:
 
 - giữ `:root` là theme mặc định
 - tạo selector như `[data-ui-theme='brand-a']`, `[data-ui-theme='brand-b']`
+- vẫn nên xuất phát từ một preset duyệt sẵn rồi mới override token cần thiết
 - chỉ override token trong file theme, không fork component

package/README.md

@@ -19,12 +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
+npm install @lucasvu/scope-ui
+npx scope-ui-init --theme sunset
+```
+
+Nếu chưa biết chọn preset nào thì mới cần xem danh sách trước:
+
+```bash
+npx scope-ui-init --list-themes
 ```
 
-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`.
+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. Dùng `--force` nếu muốn overwrite file đã tồn tại.
+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:
 
@@ -103,22 +110,33 @@ 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`
-- Chạy `npx scope-ui-init` ở project consumer sau khi đã cài `@lucasvu/scope-ui` để tạo `AGENTS.md` và `src/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` để biết màu/token phải override ở đâu
+- 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';
 ```
 
 `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.
 
-`uiThemeContract` mô tả token màu, surface, border, shadow, gradient và selector theme (`:root`, `.dark`, `[data-ui-theme='*']`) để AI không hardcode màu sai chỗ.
+`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.
 
 `AI_SETUP.md` và CLI `scope-ui-init` giúp bootstrap rule/theme cho repo consumer mà không cần copy tay.
 
@@ -126,6 +144,14 @@ import {
 
 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:
+
+```bash
+npm install @lucasvu/scope-ui
+npx scope-ui-init --list-themes
+npx scope-ui-init --theme ocean
+```
+
 ```ts
 import '@lucasvu/scope-ui/styles.css';
 import './styles/ui-theme.css';
@@ -437,7 +463,8 @@ import { LineClampTooltip } from '@lucasvu/scope-ui';
 
 ## Tuỳ chỉnh theme
 
-- Sửa tông màu, radius, shadow trong `packages/ui/src/styles.css` (biến `--primary`, `--radius`, `--shadow-*`).
+- Ưu tiên chọn một preset duyệt sẵn qua `npx scope-ui-init --theme <preset>` để giữ UI đồng bộ giữa các project.
+- Nếu cần tinh chỉnh thêm, chỉ sửa token trong `src/styles/ui-theme.css`, không restyle từng component riêng lẻ.
 - Các lớp `ui-*` đã được namespaced để tránh va chạm với CSS hiện tại.
 
 ## Gợi ý tích hợp

package/bin/scope-ui-init.mjs

@@ -5,30 +5,264 @@ import { dirname, resolve } from 'node:path'
 import process from 'node:process'
 
 const PACKAGE_NAME = '@lucasvu/scope-ui'
+const DEFAULT_THEME_PRESET = 'ocean'
+
+const THEME_PRESETS = {
+  ocean: {
+    id: 'ocean',
+    label: 'Ocean Glass',
+    description:
+      'Blue-cyan preset with clean glass surfaces. Matches the current default visual language.',
+    recommendedFor: [
+      'Admin dashboards',
+      'SaaS CRUD screens',
+      'Projects that want the existing package look',
+    ],
+    tokens: {
+      light: {
+        '--tw-background': '0 0% 100%',
+        '--tw-foreground': '222.2 47.4% 11.2%',
+        '--tw-primary': '221.2 83.2% 53.3%',
+        '--tw-accent': '199 89% 48%',
+        '--tw-success': '142.1 76.2% 36.3%',
+        '--tw-destructive': '0 84.2% 60.2%',
+        '--tw-border': '214.3 31.8% 91.4%',
+        '--radius': '0.75rem',
+        '--surface': 'rgba(255, 255, 255, 0.92)',
+        '--surface-strong': 'rgba(241, 245, 249, 0.96)',
+        '--grey': 'rgba(248, 250, 252, 0.96)',
+        '--grey-strong': 'rgba(241, 245, 249, 0.98)',
+        '--shadow-sm': '0 10px 28px -18px rgba(15, 23, 42, 0.22)',
+        '--shadow': '0 24px 60px -28px rgba(15, 23, 42, 0.3)',
+        '--primary-grad-from': '199 89% 48%',
+        '--primary-grad-to': '221.2 83.2% 53.3%',
+      },
+      dark: {
+        '--tw-background': '222.2 84% 4.9%',
+        '--tw-foreground': '210 40% 98%',
+        '--tw-primary': '217.2 91.2% 59.8%',
+        '--tw-accent': '199 89% 48%',
+        '--tw-success': '142.1 70.6% 45.3%',
+        '--tw-destructive': '0 62.8% 30.6%',
+        '--tw-border': '217.2 32.6% 17.5%',
+        '--radius': '0.75rem',
+        '--surface': 'rgba(15, 23, 42, 0.78)',
+        '--surface-strong': 'rgba(30, 41, 59, 0.92)',
+        '--grey': 'rgba(30, 41, 59, 0.88)',
+        '--grey-strong': 'rgba(51, 65, 85, 0.92)',
+        '--shadow-sm': '0 16px 32px -18px rgba(2, 6, 23, 0.48)',
+        '--shadow': '0 28px 80px -32px rgba(2, 6, 23, 0.7)',
+        '--primary-grad-from': '198.6 88.7% 48.4%',
+        '--primary-grad-to': '221.2 83.2% 53.3%',
+      },
+    },
+  },
+  sunset: {
+    id: 'sunset',
+    label: 'Sunset Ember',
+    description:
+      'Warm orange-coral preset with softer cream surfaces for branded landing or growth products.',
+    recommendedFor: [
+      'Growth products',
+      'Commerce backoffices',
+      'Projects that want a warmer visual tone',
+    ],
+    tokens: {
+      light: {
+        '--tw-background': '30 100% 98%',
+        '--tw-foreground': '20 24% 14%',
+        '--tw-primary': '14 90% 56%',
+        '--tw-accent': '29 100% 58%',
+        '--tw-success': '145 63% 38%',
+        '--tw-destructive': '0 78% 58%',
+        '--tw-border': '24 45% 89%',
+        '--radius': '0.85rem',
+        '--surface': 'rgba(255, 247, 240, 0.92)',
+        '--surface-strong': 'rgba(255, 237, 223, 0.96)',
+        '--grey': 'rgba(255, 243, 231, 0.96)',
+        '--grey-strong': 'rgba(255, 232, 214, 0.98)',
+        '--shadow-sm': '0 12px 30px -18px rgba(194, 65, 12, 0.18)',
+        '--shadow': '0 28px 64px -30px rgba(154, 52, 18, 0.24)',
+        '--primary-grad-from': '29 100% 58%',
+        '--primary-grad-to': '14 90% 56%',
+      },
+      dark: {
+        '--tw-background': '20 24% 8%',
+        '--tw-foreground': '40 33% 96%',
+        '--tw-primary': '18 100% 62%',
+        '--tw-accent': '35 100% 58%',
+        '--tw-success': '145 60% 47%',
+        '--tw-destructive': '0 73% 52%',
+        '--tw-border': '18 24% 22%',
+        '--radius': '0.85rem',
+        '--surface': 'rgba(41, 24, 18, 0.84)',
+        '--surface-strong': 'rgba(59, 34, 24, 0.9)',
+        '--grey': 'rgba(70, 42, 29, 0.88)',
+        '--grey-strong': 'rgba(92, 54, 38, 0.9)',
+        '--shadow-sm': '0 18px 36px -20px rgba(67, 20, 7, 0.48)',
+        '--shadow': '0 30px 84px -34px rgba(67, 20, 7, 0.62)',
+        '--primary-grad-from': '35 100% 58%',
+        '--primary-grad-to': '18 100% 62%',
+      },
+    },
+  },
+  forest: {
+    id: 'forest',
+    label: 'Forest Mist',
+    description:
+      'Emerald-teal preset with soft botanical surfaces for calmer productivity products.',
+    recommendedFor: [
+      'Operations tools',
+      'Internal platforms',
+      'Products that want a calmer green tone',
+    ],
+    tokens: {
+      light: {
+        '--tw-background': '138 40% 98%',
+        '--tw-foreground': '160 25% 14%',
+        '--tw-primary': '158 64% 40%',
+        '--tw-accent': '173 58% 44%',
+        '--tw-success': '145 63% 36%',
+        '--tw-destructive': '0 78% 58%',
+        '--tw-border': '143 21% 88%',
+        '--radius': '0.8rem',
+        '--surface': 'rgba(245, 252, 249, 0.92)',
+        '--surface-strong': 'rgba(232, 245, 239, 0.96)',
+        '--grey': 'rgba(240, 248, 244, 0.96)',
+        '--grey-strong': 'rgba(225, 240, 232, 0.98)',
+        '--shadow-sm': '0 12px 28px -18px rgba(5, 86, 66, 0.18)',
+        '--shadow': '0 26px 62px -30px rgba(6, 78, 59, 0.24)',
+        '--primary-grad-from': '173 58% 44%',
+        '--primary-grad-to': '158 64% 40%',
+      },
+      dark: {
+        '--tw-background': '164 35% 8%',
+        '--tw-foreground': '144 35% 96%',
+        '--tw-primary': '160 70% 46%',
+        '--tw-accent': '174 72% 45%',
+        '--tw-success': '145 68% 46%',
+        '--tw-destructive': '0 70% 52%',
+        '--tw-border': '160 20% 20%',
+        '--radius': '0.8rem',
+        '--surface': 'rgba(16, 36, 31, 0.84)',
+        '--surface-strong': 'rgba(21, 51, 44, 0.9)',
+        '--grey': 'rgba(24, 61, 52, 0.88)',
+        '--grey-strong': 'rgba(31, 77, 65, 0.9)',
+        '--shadow-sm': '0 18px 34px -20px rgba(1, 44, 34, 0.48)',
+        '--shadow': '0 30px 82px -34px rgba(1, 44, 34, 0.6)',
+        '--primary-grad-from': '174 72% 45%',
+        '--primary-grad-to': '160 70% 46%',
+      },
+    },
+  },
+  graphite: {
+    id: 'graphite',
+    label: 'Graphite Pulse',
+    description:
+      'Neutral slate preset with restrained blue accents for products that need a steadier enterprise tone.',
+    recommendedFor: [
+      'Enterprise admin panels',
+      'B2B internal tools',
+      'Projects that want a more neutral interface',
+    ],
+    tokens: {
+      light: {
+        '--tw-background': '220 18% 97%',
+        '--tw-foreground': '222 24% 14%',
+        '--tw-primary': '221 24% 32%',
+        '--tw-accent': '198 83% 44%',
+        '--tw-success': '160 56% 38%',
+        '--tw-destructive': '0 72% 54%',
+        '--tw-border': '218 17% 86%',
+        '--radius': '0.7rem',
+        '--surface': 'rgba(248, 250, 252, 0.94)',
+        '--surface-strong': 'rgba(226, 232, 240, 0.96)',
+        '--grey': 'rgba(241, 245, 249, 0.98)',
+        '--grey-strong': 'rgba(226, 232, 240, 0.99)',
+        '--shadow-sm': '0 12px 30px -20px rgba(15, 23, 42, 0.18)',
+        '--shadow': '0 28px 66px -30px rgba(15, 23, 42, 0.24)',
+        '--primary-grad-from': '198 83% 44%',
+        '--primary-grad-to': '221 24% 32%',
+      },
+      dark: {
+        '--tw-background': '222 32% 8%',
+        '--tw-foreground': '210 25% 96%',
+        '--tw-primary': '210 24% 82%',
+        '--tw-accent': '192 92% 52%',
+        '--tw-success': '158 64% 45%',
+        '--tw-destructive': '0 72% 56%',
+        '--tw-border': '217 19% 24%',
+        '--radius': '0.7rem',
+        '--surface': 'rgba(15, 23, 42, 0.82)',
+        '--surface-strong': 'rgba(30, 41, 59, 0.92)',
+        '--grey': 'rgba(30, 41, 59, 0.9)',
+        '--grey-strong': 'rgba(51, 65, 85, 0.92)',
+        '--shadow-sm': '0 18px 38px -22px rgba(2, 6, 23, 0.48)',
+        '--shadow': '0 32px 88px -34px rgba(2, 6, 23, 0.68)',
+        '--primary-grad-from': '192 92% 52%',
+        '--primary-grad-to': '210 24% 82%',
+      },
+    },
+  },
+}
+
+function exitWithMissingValue(optionName) {
+  console.error(`Missing value for ${optionName}`)
+  process.exit(1)
+}
 
 function parseArgs(argv) {
   const args = {
     force: false,
     agentsFile: 'AGENTS.md',
     themeFile: 'src/styles/ui-theme.css',
+    theme: DEFAULT_THEME_PRESET,
+    listThemes: false,
   }
 
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index]
+
     if (arg === '--force') {
       args.force = true
       continue
     }
+
     if (arg === '--agents-file') {
-      args.agentsFile = argv[index + 1] ?? args.agentsFile
+      const value = argv[index + 1]
+      if (!value || value.startsWith('--')) {
+        exitWithMissingValue('--agents-file')
+      }
+      args.agentsFile = value
       index += 1
       continue
     }
+
     if (arg === '--theme-file') {
-      args.themeFile = argv[index + 1] ?? args.themeFile
+      const value = argv[index + 1]
+      if (!value || value.startsWith('--')) {
+        exitWithMissingValue('--theme-file')
+      }
+      args.themeFile = value
       index += 1
       continue
     }
+
+    if (arg === '--theme') {
+      const value = argv[index + 1]
+      if (!value || value.startsWith('--')) {
+        exitWithMissingValue('--theme')
+      }
+      args.theme = value
+      index += 1
+      continue
+    }
+
+    if (arg === '--list-themes') {
+      args.listThemes = true
+      continue
+    }
+
     if (arg === '--help' || arg === '-h') {
       printHelp()
       process.exit(0)
@@ -47,38 +281,118 @@ Usage:
   npx scope-ui-init
     Run this after @lucasvu/scope-ui has been installed in the consumer project.
 
-  npx scope-ui-init --force
+  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
 
 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
+  --theme        theme preset id (${Object.keys(THEME_PRESETS).join(', ')})
+  --list-themes  show the approved preset list
   --help, -h     show this help
 `)
 }
 
-function createAgentsTemplate({ themeFile }) {
+function printThemeList() {
+  console.log('Approved theme presets:\n')
+
+  for (const themePreset of Object.values(THEME_PRESETS)) {
+    console.log(`${themePreset.id} - ${themePreset.label}`)
+    console.log(`  ${themePreset.description}`)
+    console.log(`  Recommended for: ${themePreset.recommendedFor.join(', ')}`)
+    console.log('')
+  }
+}
+
+function getThemePreset(themeId) {
+  return THEME_PRESETS[themeId]
+}
+
+function resolveThemePreset(themeId) {
+  const themePreset = getThemePreset(themeId)
+
+  if (themePreset) {
+    return themePreset
+  }
+
+  console.error(`Unknown theme preset: ${themeId}\n`)
+  printThemeList()
+  process.exit(1)
+}
+
+function renderTokenBlock(tokens) {
+  return Object.entries(tokens)
+    .map(([token, value]) => `  ${token}: ${value};`)
+    .join('\n')
+}
+
+function createAgentsTemplate({ themeFile, themePreset }) {
   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}\`).
 
 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
 - use root exports from \`${PACKAGE_NAME}\`
+- use \`${themeFile}\` as the only source of truth for colors, radius, surfaces, and shadows
+- 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, or shadows
+- read \`uiThemeContract\` before changing colors, surfaces, borders, radius, or shadows
 - keep UI token-driven and theme-driven
 
 Do not:
 - import from \`MainFe\` unless the task explicitly targets a legacy screen
-- hardcode brand colors inside page components when a theme token already exists
+- invent a second palette or one-off brand colors outside \`${themeFile}\`
+- restyle individual pages if the preset tokens can solve it globally
 - create duplicate Button/Input/Select wrappers unless a project-specific behavior is required
 
 Component choice:
@@ -94,20 +408,18 @@ Component choice:
 `
 }
 
-function createThemeTemplate() {
-  return `:root {
-  /* Override only the tokens you need for the project brand. */
-  /* --tw-primary: 221.2 83.2% 53.3%; */
-  /* --tw-accent: 199 89% 48%; */
-  /* --primary-grad-from: 199 89% 48%; */
-  /* --primary-grad-to: 221.2 83.2% 53.3%; */
-  /* --surface: rgba(255, 255, 255, 0.92); */
+function createThemeTemplate({ themePreset }) {
+  return `/* Generated by scope-ui-init. */
+/* Theme preset: ${themePreset.label} (${themePreset.id}) */
+/* Re-run \`npx scope-ui-init --theme <preset> --force\` to switch preset. */
+
+:root {
+${renderTokenBlock(themePreset.tokens.light)}
 }
 
-.dark {
-  /* --tw-primary: 217.2 91.2% 59.8%; */
-  /* --tw-accent: 199 89% 48%; */
-  /* --surface: rgba(15, 23, 42, 0.78); */
+.dark,
+[data-ui-theme='dark'] {
+${renderTokenBlock(themePreset.tokens.dark)}
 }
 `
 }
@@ -127,19 +439,27 @@ function writeFile(targetPath, content, force) {
 
 const options = parseArgs(process.argv.slice(2))
 
+if (options.listThemes) {
+  printThemeList()
+  process.exit(0)
+}
+
+const themePreset = resolveThemePreset(options.theme)
+
 const agentsResult = writeFile(
   options.agentsFile,
-  createAgentsTemplate({ themeFile: options.themeFile }),
+  createAgentsTemplate({ themeFile: options.themeFile, themePreset }),
   options.force,
 )
 
 const themeResult = writeFile(
   options.themeFile,
-  createThemeTemplate(),
+  createThemeTemplate({ themePreset }),
   options.force,
 )
 
 console.log(`Initialized ${PACKAGE_NAME}`)
+console.log(`- theme preset: ${themePreset.label} (${themePreset.id})`)
 console.log(`- ${agentsResult.path}: ${agentsResult.status}`)
 console.log(`- ${themeResult.path}: ${themeResult.status}`)
 console.log('')
@@ -147,3 +467,4 @@ 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(`4. Re-run this command with \`--theme <preset> --force\` if you want another approved preset.`)