@lark-apaas/coding-miaoda-sandbox-skills 0.1.0-dev.6f4e4bc → 0.1.0-dev.72ac425

package/miaoda/lark-design-prototype/references/layout-interaction.md

@@ -0,0 +1,164 @@
+# Layout And Interaction
+
+Figma, screenshots, and design drafts provide layout evidence. The goal is to convert the source into a responsive, interactive product interface that keeps the Feishu feel.
+
+## Figma / Screenshot Evidence
+
+Write `source_layout_evidence` first:
+
+- frame scope, scroll areas, and cropping relationship;
+- reading order and primary / secondary regions;
+- auto layout direction, padding, gap, alignment, wrap;
+- constraints, fill / hug, min / max, resize behavior;
+- recognizable component instances, states, variants, prototype hints;
+- color, radius, border, shadow, text style, and variable clues;
+- media slots, image ratio, and cropping method;
+- which regions enter normal document flow, and which are floating or locally positioned.
+
+When source evidence conflicts with cases, keep source evidence. Cases only provide risk reminders and transferable experience.
+
+## Source Viewport Contract
+
+For screenshot restoration, write `source_viewport_contract` before implementation:
+
+```md
+source_viewport_contract:
+  source_image_px:
+  inferred_dpr:
+  target_css_viewport:
+  browser_preview_viewport:
+  delivery_fit_rule: responsive_web_page | fixed_artboard
+  scale_rule: do not use raw screenshot pixels as CSS px
+```
+
+Do not infer the target CSS viewport from source image pixels with a single fixed DPR assumption. Browser preview must use `browser_preview_viewport`, not the default browser size.
+
+`target_css_viewport` is a calibration and browser-preview contract, not a required fixed deliverable canvas. Use it to infer proportions, typography scale, spacing, and the preview viewport. The delivered page should still render at normal browser zoom in the current viewport unless the user explicitly asks for a fixed artboard. Do not solve screenshot restoration by hard-coding the whole app shell to the target CSS viewport when the result is meant to be used as a web page.
+
+Use `delivery_fit_rule: responsive_web_page` for normal web demos, products, dashboards, tools, and IM / Docs / collaboration surfaces. In this mode, the app shell should use responsive sizing such as `100vw`, `100vh`, flex, grid, `minmax`, and breakpoints while keeping the source proportions calibrated. Use `delivery_fit_rule: fixed_artboard` only when the user explicitly asks for a fixed canvas, export board, slide-like frame, or exact-size artboard.
+
+Calibrate with stable evidence: app chrome height, sidebar width, list column width, top bar height, avatar diameter, list row height, control height, message spacing, and body text size.
+
+## Scale Calibration
+
+For screenshot restoration, run a brief scale calibration pass before full implementation:
+
+- Identify a few stable UI anchors in the source, such as navigation width, list column width, header height, avatar size, control height, message spacing, and body text size.
+- Use the anchors to choose the target viewport and base scale; do not rely on screenshot pixel dimensions alone.
+- During preview, check whether the page feels correctly scaled at normal browser zoom. If it only looks right after manual browser zoom, revisit the scale calibration before making local CSS tweaks.
+
+## Layout Conversion
+
+- Page body uses flex, grid, gap, padding, margin, min/max-width, and overflow.
+- Avoid copying full-page `top/left` coordinates or fixed canvas size.
+- Fixed dimensions are only for base elements: icons, avatars, control height, hairline borders, and local media ratios.
+- Absolute positioning is only for badges, tooltip, popover, dropdown, local visual anchors, and other truly floating elements.
+- Work pages prefer a vertical main spine; a right rail appears only when the source or information architecture clearly needs it.
+- The main workspace uses responsive width and fills the available space after the navigation shell. `main-workspace`, `main-content`, and the right content area use `width: 100%`, responsive padding, grid / flex / minmax, and breakpoints.
+- Max reading width is only for local reading content such as long-form text, settings forms, and detail descriptions. Workspaces, tables, boards, CRM, admin pages, and data pages must not apply a fixed `max-width` to the whole main workspace. Wide-screen readability is controlled through column count, table column width, right auxiliary rail, local reading width, and whitespace rhythm.
+- Layout aligns to the 4px base grid. The main content container, module titles, tables, card grids, and right rail use stable left edges, column widths, and gaps. Avoid random values and temporary offsets. Implementation should reuse spacing variables or constants. Common values are 16 / 24 / 32 / 40px. Except for font line-height, 0.5px borders, and optical icon corrections, layout values should not leave the 4px grid.
+- Page title, module title, Hero, quick entry, card grid, table container, and right rail should inherit the same content wrapper padding and left edge. Do not repair alignment with a single module's `margin-left`, temporary `width`, or offset.
+- Hover, selected, loading, error hints, and dynamic numbers must not change card height, column width, toolbar height, or the overall page rhythm.
+
+## Shell Conversion
+
+Choose the shell pattern based on the source and product semantics before handling content:
+
+- `side-nav-primary`: Side navigation is the main app anchor and usually occupies `100vh`. At standard width it stays expanded, width 224–280px. At `narrow`, it may shrink to a 64–72px icon rail; at `compact`, it becomes a drawer, top entry, or bottom entry. The right workspace should prefer white or nearly white `bg-body`; the main workspace stretches responsively within the remaining space and does not get an extra page-level large rounded content shell or light-gray backing layer.
+- `top-nav-primary`: Top navigation is the main app anchor, usually 64px high, with a `bg-body` surface and 0.5px bottom divider. Main content starts below the top bar. If an auxiliary sidebar exists, it starts below the top bar, has height `calc(100vh - 64px)`, usually uses `bg-body`, and is separated from content by a 0.5px vertical divider.
+
+Do not mix the backing relationships of `side-nav-primary` and `top-nav-primary`. In particular, do not add an extra rounded shell or gray backing layer to the right main content by default just because a page has a sidebar.
+
+## Spacing And Sectioning
+
+Feishu pages separate modules with whitespace. Common rhythm:
+
+- First-level content groups: 40px;
+- Large horizontal blocks: 24px;
+- Same-group cards or grids: 16–24px;
+- Title to content: 16px;
+- Inline icon and label: 4–8px.
+
+Quick-entry grids only fix column width and gap, not row height. The parent uses `grid-auto-rows: auto`, allowing cards in the same row to stretch to the tallest card in that row. Do not use `grid-auto-rows: 1fr`, `grid-auto-rows: minmax(...)`, `place-items: center`, `aspect-ratio`, or fixed height classes to make all rows equally tall.
+
+40px is the default vertical spacing between content groups. Local structures such as table rows, menu items, and tag groups may stay tight. Other content areas should avoid over-compression.
+
+Table rows need to be stable and single-line. Body cells use `white-space: nowrap; overflow: hidden; text-overflow: ellipsis;`. Do not stack primary and secondary information vertically inside a cell. Auxiliary information should move into separate columns, tooltip, right detail drawer, or row details. Long-text ellipsis, hover, selected, and loading should not change table row height.
+
+Content sections default to an external header and content container. The header is on top and carries the module title, description, and optional tools. The content container below carries a table, list, card grid, or business surface. Header and content container usually keep 12–16px spacing, and the content container border must not wrap the section title. Hero, floating layers, navigation, and a single detail card may use internal titles.
+
+## Responsive Expectations
+
+- `standard`: Keep the full shell, multi-column layout, and right auxiliary area. Search, filters, Tabs, and actions stay as a stable one-row toolbar.
+- `narrow`: Reduce column count, merge the right auxiliary area into the main content flow, allow tool areas to wrap, and collapse filters first into icon buttons or Dropdown.
+- `compact`: Single-column content flow, sidebar becomes an explicit entry, and complex filters collapse into IconButton + Drawer / Popover.
+
+The main workspace stays responsive at all three breakpoints: standard fills the available width after the navigation shell; narrow preserves readability through fewer columns, a moved-down right rail, and wrapping tool areas; compact becomes a single column. Do not use fixed canvas width or whole-page `max-width` that creates large meaningless whitespace on wide screens.
+
+Page-level search goes by default at the leftmost position of the `top-nav` right tool button group. Content sections only contain local search and filters, and their scope should be the current table, list, or board.
+
+When a title area contains local search, filters, Select, Tabs, or action buttons, title and tools need clear responsive responsibilities. At standard width, the toolbar stays on one row: search input is usually 280–360px, Select / DatePicker usually 160–220px, and Tabs align with filters. When space is tight, switch to wrapping or a vertical layout. Filters first become icon buttons, Dropdown, Popover, or Drawer. Do not compress long text in any language into character-by-character columns, vertical text, or one-character rows.
+
+Avoid these triggers:
+
+- Title block has no minimum readable width;
+- Search input has fixed width and cannot wrap;
+- Select / DatePicker uses `width: 100%` or `flex: 1` to occupy a whole row;
+- Filters and Tabs split into unrelated rows, breaking toolbar hierarchy;
+- `word-break: break-all` or `overflow-wrap: anywhere` is used on regular text;
+- flex children lack `min-width: 0` and a reasonable wrapping strategy;
+- Very narrow fixed-width containers carry long titles, buttons, tags, or table fields;
+- Table cells use two-line text for primary / secondary information, making row height unstable.
+
+## Collision Guard
+
+Before implementation, reserve fixed slots and wrapping rules for collision-prone areas:
+
+- top conversation header: avatar, title, metadata, badges, and right actions;
+- tabs and local toolbar;
+- side navigation selected rows, unread badges, and bottom dock entries;
+- chat / list rows: avatar, title, preview, date, status, and badges;
+- message cards, image previews, inline chips, and floating action buttons.
+
+Use flex or grid areas with `min-width: 0` for text containers. Single-line labels use `white-space: nowrap; overflow: hidden; text-overflow: ellipsis`. Multiline areas need explicit line clamp, max width, or wrapping boundaries. Avoid temporary absolute offsets for badges, avatars, and titles that belong to row layout.
+
+## Surfaces And Depth
+
+Ordinary business cards, Hero, metric cards, quick entries, table containers, right summaries, stage pipelines, and insight panels have no shadows by default. They express hierarchy through `bg-body`, 0.5px `line-border-card`, radius, title hierarchy, and whitespace.
+
+Shadows are only for floating layers outside document flow, such as dropdown, popover, tooltip, dialog, drawer, and floating menu. If a UD Card has a default shadow, override it to no shadow.
+
+Regular workspaces should usually stay within two layers: page base plus content surface. Introduce light gray backing only for clear backing, nested editing areas, or floating-layer relationships. Do not use gray backing with white cards, white cards with gray blocks, gray blocks with smaller cards, or card-in-card layouts to express hierarchy. Side navigation uses a near-white neutral background, with neutral selected fill and 500 text weight, not light-blue selected fill by default.
+
+## Interaction Conversion
+
+- Button triggers visible actions, state changes, navigation, submit, reset, drawer, dialog, or toast.
+- Tabs switch content and do more than show active styling.
+- Search and filter controls update query state, visible data, or empty state.
+- Drawer, Dialog, Dropdown, Popover, and Menu prefer component-provided APIs.
+- Tables and lists keep expected row actions, filtering, sorting, pagination, or details entry.
+- Icon-only actions need accessible names and hover / focus states.
+
+## Static Exceptions
+
+Static behavior is allowed when:
+
+- The user explicitly asks for a static mock;
+- The element is only decoration or information display;
+- Production integration is blocked and noted in the final response;
+- The source is a purely visual brand mock.
+
+## Check Questions
+
+- Has the page body moved away from fixed Figma coordinates?
+- Does screenshot restoration have `source_viewport_contract`, and does browser preview use the target CSS viewport?
+- Does the restored page feel correctly scaled at normal browser zoom based on stable source anchors?
+- Does the main workspace use responsive width and fill the available space after the navigation shell?
+- Is max reading width used only in local reading areas such as long-form text, forms, or detail descriptions?
+- Is there about 40px of visible whitespace between first-level content groups?
+- Does the title-area toolbar wrap at narrow widths?
+- Is long text still readable?
+- Are top bars, navigation, list rows, badges, tabs, and message cards free from visible collisions?
+- Do ordinary business surfaces have no shadows?
+- Has the page avoided multiple nested backgrounds, excessive accent colors, and multiple bold text layers in the same group?
+- Are visible controls interactive or covered by a static exception?

package/miaoda/lark-design-prototype/references/page-contract.md

@@ -0,0 +1,281 @@
+# Feishu Lightweight Design Contract
+
+Use this contract when the task comes from natural language, Figma, screenshots, or design drafts and needs a Feishu / Lark style page. The contract helps design decisions carry into implementation and prevents the page from turning into a template.
+
+## Core Principles
+
+- Write enough to drive implementation, and avoid unrelated fields.
+- Record source evidence, visual recipe, control style strategy, media strategy, and verification focus.
+- Figma / screenshot evidence has priority over cases; cases only provide inspiration and risk reminders.
+- Recognizable system controls should follow UD visual language and interaction semantics first; custom areas need a clear responsibility.
+
+## Recommended Fields
+
+```md
+source_of_truth:
+scope_sketch:
+source_layout_evidence:
+source_viewport_contract:
+scale_calibration:
+product_surface:
+main_user_flow:
+content_fill_policy:
+lark_style_recipe:
+layout_model:
+surface_family:
+spacing_rhythm:
+section_header_policy:
+toolbar_policy:
+top_nav_policy:
+right_rail_policy:
+typography_hierarchy:
+emphasis_budget:
+table_policy:
+control_candidates:
+ud_control_coverage:
+layout_signature_usage:
+icon_plan:
+media_decision:
+media_plan:
+states:
+responsive_plan:
+case_reference:
+style_boundaries:
+acceptance_criteria:
+verification_plan:
+open_questions:
+```
+
+Small tasks can keep 5–8 key fields. Page-level, Figma / screenshot, high-fidelity, and runnable demo tasks need a more complete contract.
+
+## Field Guide
+
+- `source_of_truth`: User input, Figma, screenshot, design draft, existing code, or combined sources. Explain tradeoffs when sources conflict.
+- `scope_sketch`: Scope sketch for natural-language tasks, including page, primary user task, main regions, key interactions, and scope boundaries.
+- `source_layout_evidence`: Required for Figma / screenshot tasks. Record reading order, main regions, auto layout, padding, gap, alignment, constraints, component instances, style clues, media slots, and responsive evidence.
+- `source_viewport_contract`: Required for screenshot restoration. Record source image pixels, inferred DPR, target CSS viewport, browser preview viewport, `delivery_fit_rule`, and the rule that raw screenshot pixels must not become CSS pixels. `target_css_viewport` is used for calibration and browser preview, not as a fixed app-shell size unless `delivery_fit_rule: fixed_artboard` is explicitly chosen. Normal web demos use `delivery_fit_rule: responsive_web_page` and should render at normal browser zoom in the current viewport.
+- `scale_calibration`: Optional but recommended for screenshot restoration. Keep it brief: record the stable source anchors used to judge scale, the base scale decision, and whether normal browser zoom feels correct. Use anchors such as navigation width, list width, header height, avatar size, control height, message spacing, and body text size; do not rely on source pixel dimensions alone.
+- `product_surface`: Product surface such as workspace, CRM, data table, AI, Docs, approval, admin console, or official site.
+- `main_user_flow`: The 1–3 most important actions after the user enters the page.
+- `content_fill_policy`: Use when the user does not clearly define content scope in a natural-language task. Record which core content stays, which modules are not proactively added, and the minimum sample-data count.
+- `lark_style_recipe`: Lightweight visual recipe. Include surfaces, color restraint, accent-color budget, no gradients, spacing grid, radius, borders, shadows, typography weight, controls, media, visual restraint, and anti-patterns.
+- `layout_model`: Document-flow structure, main columns, scroll areas, right auxiliary area, responsive main workspace width, shared content container line, responsive tracks, and floating-layer relationships.
+- `surface_family`: Background relationship among page root, sidebar, content area, cards, and floating layers. body / app-root / main-workspace / main-content / right content area should prefer white or nearly white `bg-body`. One area usually keeps at most page base and content surface; avoid multiple nested background layers.
+- `spacing_rhythm`: Spacing rhythm between first-level content groups, internal cards, title-to-content, and controls. Content groups default to 40px. Record page-level gap tokens such as `section_gap: 40px`, `module_gap: 16px`, `card_gap: 16–24px`, `rail_gap: 24px`, and note that quick entries use equal height within the same row, with row height determined by the tallest card in that row.
+- `section_header_policy`: Record whether content section titles are external. Except for Hero, overview summary cards, small KPI cards, floating layers, navigation, and single detail cards, module titles should sit outside bordered content containers.
+- `toolbar_policy`: Record placement relationships for search, filters, Tabs, view switches, and local actions. Page-level search goes by default at the leftmost position of the `top-nav` right tool group; local filters and Tabs align as a toolbar.
+- `top_nav_policy`: Use when a top bar is present or shell quality matters. Record shell role, height, left identity, right utilities, divider, search placement, and whether business actions stay in the page title area.
+- `right_rail_policy`: Use when a right auxiliary area is present or considered. Record necessity, role, width, surface pattern, text weight, rail groups, responsive merge behavior, and what should remain in the main flow.
+- `typography_hierarchy`: Font size / weight / color for page title, module title, card title, body text, metadata, and numbers.
+- `emphasis_budget`: Use when typography feels heavy or the page has forms, tables, cards, or right rails. Record which single layer may use 600 / 500 in each region, and which labels, descriptions, button text, links, metadata, and body copy stay 400.
+- `table_policy`: When the page includes tables, record single-line cells, 400 body weight, long-text ellipsis / tooltip / detail handling, and stable row height.
+- `control_candidates`: Needed control patterns such as Menu, Button, Input, Table, Tabs, Card, Tag, Avatar, Drawer, Dialog, and Empty.
+- `ud_control_coverage`: Required for Figma / screenshot / high-fidelity tasks. Record whether visible system controls follow UD visual language, interaction semantics, states, tokens, and accessibility, and where custom code is allowed.
+- `layout_signature_usage`: Record only matched framework signatures such as top-nav, side-navigation, quick-action-module, and hero-card. When top-nav or side-navigation is matched, add `shell_pattern: side-nav-primary / top-nav-primary`. Omit when not matched.
+- `icon_plan`: Record when the page contains icons. Regular page UI icons choose catalog `outlined`, preferably v2 when semantically suitable. Record area-level strategy, source visual type when restoring, matched catalog `name`, description match reason, color semantic, `hash` / `darkHash`, family, visual type, and final SVG URL. Natural-language generation must match catalog descriptions by action / object / state semantics and keep the same family / type within a group. Figma / screenshot restoration must preserve source visual type: outlined, filled, or colorful. File-type identification may use File v2 colorful and must additionally record `usage: file_type_identification`, file type, shape normal / round, and consistency within the same area.
+- `media_decision`: Decide which regions need illustrations, thumbnails, avatars, product images, important entry icons, or empty-state images. When Hero, welcome areas, recommended content, product entries, empty states, workspace home pages, or business summaries carry first-glance explanation, plan a visual anchor by default; if no media is used, explain why.
+- `media_plan`: When media is needed, record asset source, match reason, target slot, ratio, cropping, and fallback.
+- `states`: loading, empty, disabled, error, success, selected, expanded, drawer-open, dialog-open, and similar states.
+- `responsive_plan`: Layout changes under standard, narrow, and compact widths, especially how the main workspace fills available space, how title area + search / filters / action buttons wrap, and where local max reading width is allowed.
+- `case_reference`: Matched case, reference weight, borrowed points, and avoided points. Use `none` when no case matches.
+- `style_boundaries`: Boundaries that strongly affect Feishu style, such as fewer dividers, no ordinary card shadows, left-aligned entries, and media only when needed.
+- `acceptance_criteria`: User-visible acceptance criteria.
+- `verification_plan`: Build, browser, breakpoint, interaction, and visual checks.
+- `open_questions`: Only record questions that affect implementation.
+
+## Figma / Screenshot Writing Pattern
+
+```md
+source_layout_evidence:
+  reading_order: sidebar -> top tools -> hero -> primary list -> right summary
+  layout: shell grid, content stack, optional right rail
+  container_line: page title, hero, section headers, card grid and table align to one wrapper
+  grid_tracks: main minmax(0, 1fr), optional rail 320-384px, rail gap 24px
+  auto_layout: major modules use vertical stack; card group wraps
+  components: Menu, Button, Input, Table, Tag, Avatar, custom hero media slot
+  visual_signals: white workspace, light borders, 8px cards, no card shadow
+  responsive: right rail merges below narrow width; toolbar wraps before title compresses
+
+source_viewport_contract:
+  source_image_px: source image dimensions
+  inferred_dpr: inferred from source context and anchors
+  target_css_viewport: target CSS viewport
+  browser_preview_viewport: preview viewport
+  delivery_fit_rule: responsive_web_page
+  scale_rule: do not use raw screenshot pixels as CSS px
+
+scale_calibration:
+  source_anchors: navigation width, list width, header height, avatar size, control height, body text
+  scale_basis: chosen from stable anchors, not source pixels alone
+  normal_zoom_check: page should feel correctly scaled without manual browser zoom
+
+ud_control_coverage:
+- detected: primary action
+  follow_ud_style: Button
+  custom_allowed: false
+- detected: search
+  follow_ud_style: Input
+  custom_allowed: false
+- detected: hero composition
+  follow_ud_style: Card + custom media slot
+  custom_allowed: true
+  reason: business composition and media placement need custom layout; inner CTA follows UD-style button styling.
+
+layout_signature_usage:
+- component: side-navigation
+  shell_pattern: side-nav-primary
+  signature: full-height left rail, 224-280px expanded, 38-40px left-aligned icon + label rows
+- component: top-nav
+  shell_pattern: top-nav-primary
+  signature: 64px bg-body bar, page search at right tool group leftmost, unified 28px icon buttons
+
+top_nav_policy:
+  role: product / space identity and low-emphasis utilities
+  height: 56-64px
+  business_actions: page title area by default
+
+right_rail_policy:
+  role: helper rules / approval path only when useful
+  width: 320-360px
+  surface: plain_helper_rail or light_panel_rail
+  responsive: merge below main flow at narrow width
+
+emphasis_budget:
+  page_title: one 600 layer
+  section_and_labels: 500 only for titles / form labels / selected state
+  body_and_actions: descriptions, helper text, button labels, links, metadata stay 400
+```
+
+## Media Writing Pattern
+
+```md
+media_decision:
+- region: hero visual
+  media_needed: true
+  reason: welcome / summary needs a visual anchor
+
+media_plan:
+- region: hero visual
+  source_order: card-illustration-library -> UD illustration -> product asset -> generated_bitmap
+  library_lookup:
+    searched_keywords:
+    candidate_assets:
+    decision: use_library / reject_library
+    reject_reason:
+  selected_source:
+  slot_ratio:
+  handling: cover / contain / transparent
+  fallback:
+```
+
+Whenever illustrations, avatars, product images, entry icons, or empty-state images are needed, record `library_lookup` first. If the library has a semantically fitting and accessible asset, use the library first. Use `generated_bitmap` only when the library is unsuitable, inaccessible, or the current slot needs a more specific asset. If recommended content, product entries, or workspace home pages become only text and outlined icons, reevaluate whether a visual anchor is missing.
+
+Generated images only create the independent visual element needed by the current media slot, such as a data visual, light illustration, avatar, product image, entry icon, empty-state graphic, or recommendation cover. Content must match the current module theme. The style should be polished, minimal, and light, and may become a local visual focus, but must not overpower the title, main content, or actions. Do not generate a full page UI, complete dashboard, navigation bar, sidebar, table page, or browser shell.
+
+## Content Filling Pattern
+
+When the user only gives a page direction, business name, or broad goal, start with the minimum content set.
+
+```md
+content_fill_policy:
+  confidence: low
+  initial_screen_budget:
+    visible_content_groups: 2-3
+    table_or_list_samples: 5-8
+    card_samples: 3-4
+    kpi_count: 0-3, only when tied to the main task
+    auxiliary_regions: 0-1, only when useful
+  keep:
+    - product identity and primary task
+    - optional Hero or primary task area
+    - one main content area
+    - necessary primary action
+    - a small set of realistic samples
+  hold_back:
+    - KPI wall
+    - long list
+    - right-side insights
+    - recommended content
+    - recent visits
+    - multi-level navigation
+  sample_limit: only enough to show structure
+```
+
+When the user provides explicit data, a complete business flow, Figma / screenshot evidence, or specified modules, fill content according to the source. Without evidence, keep the page clean and avoid filling the canvas for a sense of completeness. The first pass may keep obvious whitespace, then expand based on user feedback.
+
+Write `hero-card` decisions into `layout_signature_usage`. It suits welcome, task reminders, smart suggestions, CRM / sales summaries, data-insight entries, recommendations, and empty states. Table directories, settings, audits, approval details, member permissions, and strong operation forms default to no Hero.
+
+## Section Header Pattern
+
+Content sections default to an external header plus content container:
+
+```md
+section_header_policy:
+- section: Customer List
+  header: outside_surface
+  surface_contains: filters + table
+  exception: false
+- section: Today Summary
+  header: internal_allowed
+  exception: overview_card
+```
+
+The external header can contain the module title, description, more entry, filter summary, view switch, or right-side tools. The content container below carries the table, list, card grid, or business surface. Do not let one border wrap both "section title + content".
+
+## Toolbar Pattern
+
+```md
+toolbar_policy:
+  page_search:
+    placement: top-nav right tool group, leftmost
+    scope: page/global
+  local_toolbar:
+    items: Tabs + filters + view switch + actions
+    alignment: one row on standard width
+    control_width:
+      search: 280-360px when local search is required
+      select: 160-220px
+    narrow_behavior: filters collapse to IconButton + Dropdown / Popover / Drawer
+```
+
+Only keep search inside a content section when it has a clear local scope. Do not stretch filter controls with `width: 100%` or `flex: 1`; when space is tight, collapse filters into icon buttons instead of placing a long Select on its own row.
+
+## Acceptance Criteria
+
+Acceptance criteria should be judged from the user's view:
+
+```md
+acceptance_criteria:
+- The first screen identifies product identity, primary task, and main content.
+- Top navigation, when present, identifies product / space and low-emphasis utilities; page-level business actions stay in the page title or primary task area unless source evidence places them in the top bar.
+- Right helper rail, when present, has a clear helper role, low visual weight, 320-360px standard width, and merges into the main flow at narrow width.
+- Primary controls are interactive or clearly marked as static display.
+- Text is not compressed at standard / narrow / compact widths, and title toolbars can wrap.
+- Page title, module title, Hero, quick entry, card grid, and table left edges align to the same content container line; main gaps, padding, column widths, and offsets follow the 4px base grid.
+- Page-level search sits at the leftmost position of the top-nav right tool group; filters, Tabs, and view switches align as one toolbar group.
+- When top-nav / side-navigation is matched, it follows the corresponding `shell_pattern`: navigation position, background, size, selected state, collapse behavior, and search placement are not mixed.
+- Ordinary business cards have no shadow, borders are light, content groups are about 40px apart, and information feels clean.
+- Quick entries and lightweight recommendation entries use equal height within the same row. The parent uses `grid-auto-rows: auto`, and every card in one row takes the height of the tallest card in that row. There is no fixed height or whole-group large height causing bottom whitespace. Icon containers may use low-saturation, low-opacity blue fills.
+- Table body cells are single-line; customer names, amounts, owners, times, and action links stay 400 weight, with ellipsis or detail handling for long text.
+- Side navigation uses a near-white neutral background and selected state uses neutral fill plus 500 text weight, not light-blue fill or brand-blue text by default.
+- Blue and other accent colors are only used for primary actions, links, focus, current state, real status, and a small amount of brand identification, not ordinary decoration or large backgrounds.
+- Page UI icons come from the catalog; regular icons use `outlined`, match catalog descriptions by semantic intent, and color matches action, status, current, disabled, or emphasis semantics. File-type identification may use File v2 colorful as a whole group with the same type and same shape.
+- Page UI has no gradients.
+- The main workspace stretches responsively within the available space after the navigation shell; the whole `main-workspace` / `main-content` has no fixed max width.
+- Default body text, descriptions, table content, and card descriptions stay 400. One information group does not have multiple bold text layers.
+- Emphasis budget is visible in the result: one page-level 600 title, limited 500 labels / section titles, and 400 body, helper, button, link, and metadata text by default.
+- One area usually keeps only page base and content surface. There is no gray backing with white cards, white cards with gray blocks, or gray blocks with smaller cards.
+- Except for Hero, overview summary cards, small KPI cards, floating layers, navigation, and single detail cards, content sections have an external header and the title is not wrapped inside a bordered container.
+- When the user request is vague, page content stays restrained: the first screen usually has only 2–3 visible content groups and does not proactively stack unrelated modules or large sample data.
+- System controls in Figma / screenshots follow UD visual language, states, and semantics first.
+- Hero, welcome area, recommended content, product entry, or empty state that needs a visual anchor has checked the illustration library or recorded generated-image fallback.
+```
+
+## Avoid Recording
+
+- Implementation details that the page will not actually use;
+- Directly copied raw Figma colors as implementation tokens;
+- Fixed page-template order;
+- Unrelated modules added only because a case has them;
+- Images with no source or responsibility;
+- Audit fields unrelated to the current task.

package/miaoda/lark-design-prototype/references/product-patterns.md

@@ -0,0 +1,93 @@
+# Product Patterns
+
+Read only the sections relevant to the current task. Product patterns help judge the primary task and component tendency, not fixed module order.
+
+## App Shell / Side Navigation
+
+Persistent side navigation suits primary entries, space switching, and long-running workflows. Use icon + label by default, keep left alignment, and maintain a single current item. At standard width, the sidebar is usually 224–280px; navigation items are 38–40px high, 6px radius, 8px horizontal padding, 18–24px icons, 10–12px icon-to-text gap, and 2px vertical spacing between items. At compact viewports, it can become a top entry, drawer, or bottom navigation, but current page identity must stay visible. Collapsed state must not compress text navigation into initials or single characters.
+
+When the top bar is the main frame, the left sidebar is only auxiliary navigation. It starts below the top bar, usually uses `bg-body`, and is separated from content by a 0.5px vertical divider.
+
+## Workspace / Portal
+
+Suitable for office home pages, collaboration entries, and portal aggregation pages. You can read `references/cases/workspace-home.md` for low-weight inspiration.
+
+Tendencies:
+
+- vertical main spine;
+- light welcome Hero or key summary appears only when needed;
+- quick entries, recommended content, and recent visits are decided by the task;
+- right auxiliary area remains only when it has a clear information responsibility;
+- large workspaces keep light surfaces and few dividers.
+
+## CRM / Sales Workspace
+
+Suitable for customer operations, sales dashboards, opportunity progression, and follow-up tasks.
+
+Tendencies:
+
+- the main anchor is customers, opportunities, follow-up tasks, forecast summary, or stage progress;
+- CRM home pages, sales dashboards, and growth summaries may use Hero to carry one key judgment, a small set of actions, and optional data visual;
+- data lists keep fields that drive action;
+- metrics and summaries stay light, with no ordinary card shadows;
+- illustrations appear only in Hero, empty states, entries, or explanatory summaries when needed;
+- sidebars and top tools keep a clean work-product rhythm.
+
+## Data Table / Directory
+
+Suitable for Base, file directories, data views, and knowledge-base directories. You can read `references/cases/data-table.md`.
+
+Tendencies:
+
+- table, list, or directory grid is the primary path;
+- filters, search, view switches, and pagination follow UD-style control patterns;
+- table body stays single-line and 400 weight. Do not stack customer name + industry, object name + description, or time + note inside one cell; move auxiliary information into columns, tooltip, or detail panel.
+- thumbnails, file icons, and metadata enhance realism;
+- avoid turning the data primary path into a decorative dashboard.
+
+## AI / Conversational Tools
+
+Suitable for AI assistants, knowledge Q&A, agent entries, and generation tools. You can read `references/cases/conversational-ai-home.md`.
+
+Tendencies:
+
+- the main anchor is input area, assistant identity, recommended questions, or response stream;
+- home-style AI assistants can use Hero to express assistant identity, capability boundary, and one main input / primary action;
+- AI visuals stay restrained and only serve real intelligent capability;
+- recommended questions need to be specific and executable;
+- sidebar history and tool entries stay clean and clear.
+
+## Docs / CCM
+
+Document surfaces express ownership, recent use, sharing state, and create entries. Lists and directories should be scannable. Document categories can use tabs, filters, or directory tree.
+
+Typical components: Table / List, Tabs, Button, Dropdown, Tag, Empty, Dialog, Drawer, Upload.
+
+## Calendar
+
+Calendar pages emphasize time hierarchy. Event cards need clear encoding of state, time, participants, location, or meeting entry.
+
+Typical components: Calendar / DatePicker, Card, Tag, Avatar, Popover, Drawer, Button.
+
+## Approval / Workflow
+
+Approval pages emphasize current state, process chain, risk fields, attachments, and operation history. The primary action area should be stable.
+
+Typical components: Form, Steps, Timeline, DetailsDisplay, Table, Tag, Button, Dialog, Drawer.
+
+## Admin / Settings
+
+Settings and admin pages should be quiet and practical. Fields are organized by section, and members, permissions, apps, audit logs, and policies prefer tables.
+
+Typical components: Layout, Menu, Form, Table, Switch, Select, Button, Dialog, Drawer.
+
+## Official Site / Solution Center
+
+Official sites and solution centers can be more expressive, while still staying clean, trustworthy, and product-signaling. You can read `references/cases/official-home.md`.
+
+Tendencies:
+
+- first screen clearly states product or solution theme;
+- single primary CTA;
+- product UI image, solution graphic, or real business thumbnail as visual anchor;
+- lower sections provide functions, scenarios, customer trust, and entries.

package/miaoda/lark-design-prototype/references/prompt-expansion.md

@@ -0,0 +1,107 @@
+# Prompt Expansion
+
+Use this reference when the source of truth is natural language and the prompt is vague, implies multiple pages, or gives detailed layout without interaction details. Clear single-page requests only need a short `scope_sketch` before entering the contract.
+
+## Tiers
+
+- Tier 1, clear single page: The user clearly states the page or component and it maps directly to a Feishu enterprise pattern, such as an approval list, user detail drawer, or permission management page. Write a brief 3–5 line sketch.
+- Tier 2, vague single page: The user only says CRM, data dashboard, workspace, and similar terms, and the primary view or primary object is not clear enough. First reference `product-patterns.md`, choose the most conservative main pattern, and write the inference into `conservative_assumptions`. Use only the minimum first-pass content set and keep the view clean.
+- Tier 3, detailed layout: The user has already provided a structure such as left navigation, top toolbar, and main content area, but has not specified interactions, states, or responsive behavior. Keep the structure and fill behavior and states for every region.
+- Tier 4, multi-page or system-level: The user asks for a complete system, platform, or admin suite. First define the page list and scope boundaries, then write a sketch for the primary page.
+
+## Scope Sketch
+
+Natural-language tasks need `scope_sketch` before the contract. It acts like visible layout evidence from a screenshot and locks intent and scope.
+
+```md
+scope_sketch:
+  pages:
+    - name:
+      primary_task:
+      key_regions:
+      key_interactions:
+      key_states:
+  flow_relationships:
+  scope_boundary:
+    in:
+    out:
+  conservative_assumptions:
+  must_resolve:
+```
+
+Field guide:
+
+- `pages`: Pages or top-level views in scope. A single-page task has one item.
+- `primary_task`: The primary work the user completes on the page, not a component list.
+- `key_regions`: Shell, navigation, header, filters, content, side rail, floating layers, and feedback.
+- `key_interactions`: Triggered actions and state changes, such as filters updating a table or row click opening a drawer.
+- `key_states`: loading, empty, filtered-empty, error, selected, drawer-open, dialog-open, and similar states.
+- `flow_relationships`: Navigation or state transitions between pages; omit for a single-page task.
+- `scope_boundary.in`: Pages, views, and capabilities completed in this round.
+- `scope_boundary.out`: Related capabilities clearly excluded, with reason.
+- `conservative_assumptions`: Conservative inferences based on common Feishu patterns.
+- `must_resolve`: Questions that affect page structure, navigation, or primary interaction and cannot be conservatively filled.
+
+## Expansion Methods
+
+Tier 1: Write a compact sketch including primary task, key regions, key interactions, and key states.
+
+```md
+scope_sketch:
+  pages:
+    - name: Approval List
+      primary_task: users view, filter, and operate pending approval records
+      key_regions: content header, search/filter toolbar, data table, pagination, row detail drawer
+      key_interactions: search / filters update table, row click opens detail drawer, batch selection triggers batch actions
+      key_states: loading, empty, filtered-empty, selected, drawer-open
+  scope_boundary:
+    out: approval initiation flow keeps only an entry point
+  conservative_assumptions:
+    - approval statuses default to pending, approved, rejected, and withdrawn
+```
+
+Tier 2: Choose the main pattern from `product-patterns.md`. If two patterns are both reasonable, prefer the one with clearer data and a more stable primary path, and keep the other as an open question.
+
+For vague single pages, add a default `content_fill_policy`: keep product identity, primary task, optional Hero or primary task area, one main content area, necessary primary action, and a small set of samples. Do not proactively add KPI walls, long lists, right-side insights, recommended content, recent visits, quick entries, or multi-level navigation unless the primary task needs them. First stabilize the main content white base, neutral sidebar selected state, a small amount of accent color, restrained font weight, at most two surface layers, and the 4px grid. Then add content.
+
+First-pass content budget:
+
+- The first screen usually has only 2–3 visible content groups.
+- Table / list samples use 5–8 rows; card samples use 3–4 items.
+- KPIs appear only when the primary task needs them, with 1–3 items, and no full metric wall.
+- Right auxiliary areas and recent visits are added only when directly needed by the primary task. Omit by default first.
+- The bottom of the page may keep whitespace. Do not fill the view with unsupported content.
+
+When the page name or scene naturally needs first-glance intent, the opening can become `hero-card`, such as workspace, portal, home page, launch page, AI assistant, CRM / sales summary, data-insight entry, recommendation, and empty state. Strong table, settings, audit, approval detail, and form tasks default to title-area openings.
+
+Tier 3: Accept the user-provided layout structure and fill four things:
+
+- Whether every region is static display, clickable entry, or dynamic data list.
+- Which regions need loading, empty, error, and filtered-empty states.
+- Ownership of hover, active, selected, and disabled states for every control.
+- How regions collapse, wrap, or move at the compact breakpoint.
+
+Tier 4: First build a page list:
+
+- `primary`: primary page fully implemented in this round.
+- `secondary`: placeholder pages connected by navigation.
+- `out`: pages or capabilities clearly excluded.
+
+A complete interactive primary page is usually better than multiple half-finished pages. Every navigation item needs a target, even if that target is a recorded placeholder page.
+
+## Ambiguity Handling
+
+Ask the user first when:
+
+- The number of top-level pages is unclear and affects navigation structure.
+- The primary task cannot be reasonably inferred from the prompt.
+- User constraints directly conflict with mature Feishu / UD patterns and affect component candidates.
+
+Fill conservatively when:
+
+- Field names, status labels, and a small set of sample data are needed.
+- A secondary function can use a drawer or placeholder page.
+- Icon intent has a common default.
+- Mock data and real data source are unspecified.
+
+Record conservative fill-ins in `conservative_assumptions` so the user can correct them later.