@lucasvu/scope-ui 0.0.6 → 0.0.8

package/AI_SETUP.md

@@ -43,6 +43,8 @@ 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.
+
 ```css
 :root {
   --tw-primary: 12 88% 56%;

package/README.md

@@ -114,8 +114,9 @@ Nếu muốn AI render UI đúng và ổn định theo thư viện này, đừng
 - 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
+- Để 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`
+- `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
 - Cho agent đọc `uiScreenBlueprint`, `uiThemeContract` và `uiThemePresets` để biết screen recipe, preset và token nào được phép override

package/bin/scope-ui-init.mjs

@@ -349,37 +349,87 @@ Theme preset summary:
 - ${themePreset.description}
 - Recommended for: ${themePreset.recommendedFor.join(', ')}
 
-UI build workflow:
+## 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.
 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.
+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, 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:
+8. Before finishing, run the output checklist in this file.
+
+## Screen Brief
+
+Complete this brief before writing JSX:
+
+\`\`\`yaml
+pageKind: list | form | detail | dashboard
+routeUrl:
+sidebarItems:
+  - id:
+    title:
+    href:
+activeSidebarItemId:
+breadcrumbs:
+  - label:
+    href:
+    current:
+pageTitle:
+pageSubtitle:
+primaryAction:
+  label:
+  href:
+secondaryActions:
+  - label:
+    href:
+summaryStats:
+  - label:
+    value:
+    delta:
+    trend:
+filters:
+  - type:
+    label:
+    key:
+tableColumns:
+  - key:
+    title:
+    type:
+rowActions:
+  - label:
+    key:
+formSections:
+  - title:
+    fields: []
+fields:
+  - name:
+    type:
+    label:
+    required:
+    helperText:
+detailSections:
+  - title:
+    type:
+emptyState:
+  title:
+  description:
+  actionLabel:
+permissions: []
+\`\`\`
+
+## 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\`
+
+## Hard Rules
+
 - 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}\`
@@ -395,7 +445,8 @@ Do not:
 - 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:
+## Component Choice
+
 - \`Input\` for short text
 - \`Textarea\` for multiline text
 - \`Select\` for small fixed options
@@ -405,6 +456,18 @@ Component choice:
 - \`MultiSelect\` for multi-pick
 - \`Field\` only for custom controls or grouped content
 - \`DataTable\` for tabular records
+
+## Output Check
+
+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 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.
 `
 }
 

package/package.json

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