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

package/miaoda/lark-design-prototype/references/component-selection.md

@@ -0,0 +1,134 @@
+# Control Selection
+
+Use this reference to map prompts, Figma, screenshots, or product workflows into a Feishu / Lark control and layout structure. The goal is to preserve a native UD feel while still leaving room for page composition.
+
+## Decision Flow
+
+1. Split regions: shell, navigation, title area, toolbar, main content, auxiliary area, floating layer, feedback.
+2. Identify semantics: button, entry, navigation, list, table, filter, status, avatar, media, empty state.
+3. Recognizable system controls follow UD visual language first: Button, Input, Select, DatePicker, Checkbox, Radio, Switch, Tabs, Table, Menu, Dropdown, Tooltip, Popover, Drawer, Dialog, Tag, Badge, Avatar, Empty, Skeleton, Pagination.
+4. When the UD default visual does not fully match the source, first adapt with tokens, size, outer layout, class, and local CSS.
+5. Only customize when normal UD-style control patterns cannot satisfy source evidence, and record the reason. In that case, reproduce interaction semantics, tokens, states, and accessibility with native structure.
+6. Write `control_candidates`, `ud_control_coverage`, and the necessary `layout_signature_usage`.
+
+## UD-Style Objects
+
+- Actions: Button, IconButton, Dropdown, Tooltip, Popover.
+- Forms: Input, TextArea, Select, DatePicker, Checkbox, Radio, Switch, Upload.
+- Data and navigation: Table, Pagination, Tabs, Menu, Breadcrumb, List row pattern.
+- Floating layers and feedback: Drawer, Dialog, Popconfirm, Empty, Skeleton, Loading.
+- Status and identity: Tag, Badge, Avatar, Progress, Timeline.
+
+## Objects That Can Be Custom
+
+- Page shell, responsive grid, and module spacing;
+- Business composition containers, such as welcome areas, business summaries, recommendation cards, and entry groups;
+- Media slots, image cropping, and illustration placement;
+- Composite business cards that UD does not directly cover.
+
+Inside custom compositions, buttons, inputs, tags, avatars, dropdowns, tabs, tables, drawers, and dialogs still follow UD-style sizing, states, and semantics.
+
+## Content Section Titles
+
+Except for Hero, floating layers, navigation, and single detail cards, content sections default to an external header plus a content container. Module titles, descriptions, filter entries, more actions, and view switches sit above the content container. Bordered Card, Table, List, or business surfaces only wrap the real content.
+
+Do not put section titles such as "Customer List", "Quick Entry", "Recommended Content", "Recent Activity", or "Related Apps" inside the card border. Repeated cards can have their own card titles, but those titles do not replace the section title.
+
+## Common Semantic Mapping
+
+| User Intent | Preferred Choice | Notes |
+| --- | --- | --- |
+| Submit, confirm, create, save, delete, filter | Button / IconButton | These are command actions. |
+| Enter an object, app, workflow, or recommended content | Card / List row pattern | The whole card can be clickable and is styled as an entry card. |
+| Data list, approval, members, logs | Table / List + Tag + Dropdown | Table cells stay single-line and 400 weight; avoid stacking primary and secondary information in one cell. |
+| Search and filter | Input / Select / DatePicker / Button / IconButton / Dropdown / Popover | Page-level search goes to the leftmost position of the top-nav right tool group; local filters and Tabs form one toolbar, and filter controls do not stretch full row. |
+| Navigation | Menu / Tabs / Breadcrumb | Current location must be clear. |
+| Detail and edit | Drawer / Dialog / Form | Drawer suits contextual tasks; Dialog suits blocking decisions. |
+| Empty result | Empty + Button / Illustration | Explain the state and next step. |
+| Status, category, priority | Tag / Badge | Functional colors are only for real statuses. |
+| Avatar and identity | Avatar / Badge | Do not use avatars with no source. |
+| Hero, recommendation, welcome, product entry | Card / custom media slot + UD-style child controls | Media appears only when needed, and the source must be clear. |
+
+## Entry Cards And Recommendation Cards
+
+Quick entries, app entries, and lightweight recommendation entries use equal-height cards within the same row. The common structure is a 36–40px icon container on the left and title / description on the right. Cards use 16px vertical padding and 20–24px horizontal padding. The parent card grid uses `grid-auto-rows: auto` and may use `align-items: stretch` or card `height: 100%`, so cards in the same row take the height of the tallest card in that row. Do not write fixed `height`, large `min-height`, `aspect-ratio`, `grid-auto-rows: 1fr`, `grid-auto-rows: minmax(...)`, `place-items: center`, or fixed height classes such as `h-24 / h-28 / h-32` to unify entry heights. Descriptions use up to 2 lines, and line-height is shaped by real content; short-copy entries only follow the tallest card in the same row and do not create extra bottom whitespace.
+
+Icon containers may use low-saturation, low-opacity blue fills such as `rgba(20, 86, 240, 0.06–0.10)`, with icons staying small-area semantic colors. This background only provides light support and is not a status category; keep one background strategy across the same entry group.
+
+When recommended content carries discovery, learning, template, project material, knowledge accumulation, or product-entry responsibilities, first decide whether it needs a thumbnail, light illustration, product image, or File v2 file icon. A group of recommendation cards with only title and description can look flat, so prefer a responsible media slot; use light icon cards only when there is no media responsibility.
+
+## Framework Signature Usage
+
+top-nav, side-navigation, quick-action-module, and hero-card are used only when the page truly needs them. When matched, record:
+
+```md
+layout_signature_usage:
+- component: side-navigation
+  reason: the page needs persistently visible primary entries
+  shell_pattern: side-nav-primary
+  signature: fixed #f9f9f9 rail, left-aligned icon + label items, #1f23290d selected state
+  freedom: width, nav item count and grouping follow current information architecture
+```
+
+Framework signatures constrain role, alignment, state, and style boundaries. Module order, business content, quantity, proportion, and illustration form are decided by the current task.
+
+`hero-card` can be actively matched by scene: use it for workspaces, portals, home pages, launch pages, AI assistants, CRM / sales summaries, data-insight entries, recommendations, and empty states when the first glance needs to explain page intent. Table directories, settings, audits, approval details, member permissions, and strong operation forms default to a title area + tool area opening.
+
+## Shell Pattern Decision
+
+When a page needs a navigation shell, choose one primary mode first:
+
+- `side-nav-primary`: The left rail is the main app anchor. Suitable for CRM, back-office systems, admin consoles, workspaces, and data lists. The sidebar is usually 224–280px and expanded at standard width; collapsed width is 64–72px. The sidebar background must be written directly as `#f9f9f9`, and the selected item background directly as `#1f23290d`; use hex values directly in implementation and do not call color tokens. The right workspace continues to use white or nearly white `bg-body` and a responsive content container. Do not force an extra page-level large rounded content shell or light-gray backing layer.
+- `top-nav-primary`: The top bar is the main app anchor. Suitable for Docs, tables, knowledge bases, collaboration spaces, AI assistants, and canvases. The top bar is usually 64px, with a right tool group containing page-level search, tool icons, and avatar. If a sidebar exists, it is an auxiliary sidebar below the top bar, usually using `bg-body` and a 0.5px vertical divider.
+
+When `top-nav` is matched, page-level search goes at the leftmost position of the top bar right tool group. Standard width can use a search input; tight space uses a search icon button. Do not duplicate both search entries in the same top bar.
+
+When `side-navigation` is matched, navigation rows use left-aligned icon + label structure and do not use centered Button styling. The main sidebar uses fixed `#f9f9f9` and stays low-presence; current uses fixed `#1f23290d`; selected item text uses 500 weight. Use blue selected state only when the product clearly uses blue navigation as its primary identity. Items in the same navigation group keep 2px vertical spacing so selected or hover blocks do not touch.
+
+Navigation, lists, tables, and entry cards use font weight only to emphasize current location or primary text. Unselected navigation, auxiliary descriptions, metadata, and table body text default to 400; selected navigation, module titles, table headers, buttons, and key numbers may use 500. Blue and other accent colors are only for primary actions, links, focus, current state, real status, and a small amount of brand identification. They are not used for ordinary card backgrounds, decorative lines, icon matrices, category tags, large KPI emphasis, or entries without state meaning.
+
+Regular page UI icons use catalog `outlined`, preferably v2 when semantically suitable, and match catalog descriptions by semantic intent. Navigation, toolbars, entry cards, table row actions, category helpers, and ordinary object types use outlined icons, with color chosen from `icon-n1` / `icon-n2` / `icon-n3` / `icon-disabled` or real operation status. Do not use filled icons, emoji, characters, or hand-written SVG for regular UI without source evidence. File lists, recent documents, attachment lists, document cards, and file directories can use File v2 colorful as a group. Screenshot / Figma restoration should preserve the identified source visual type: outlined, filled, or colorful. Brand positions may use approved Feishu / Lark logotypes. Icons in the same explicit area must stay consistent by family, version, and shape.
+
+## Alignment Principles
+
+In work pages, navigation items, quick entries, app entries, recommendation entries, list rows, and right-side summary rows default to left alignment. Icon + title + description structures use horizontal left alignment. Centering only suits icon buttons, avatars, logos, pure numeric small pills, empty-state illustrations, and clearly display-oriented visuals.
+
+## Toolbar Rules
+
+Page-level search goes by default at the leftmost position of the `top-nav` right tool button group. Search inside a content section only works on local data in the current table, list, or board and does not act as global search.
+
+Filters, Tabs, view switches, and local actions should align as one toolbar group. At standard width, search inputs are usually 280–360px, Select / DatePicker usually 160–220px, and they must not use `flex: 1` or `width: 100%` to stretch across the row. When space is tight, filters collapse into IconButton + Dropdown / Popover / Drawer. Tabs stay readable and may become a Dropdown or horizontal scroll when needed.
+
+## Media Principles
+
+Plan media by responsibility. Welcome, Hero, recommended content, product entries, empty states, workspace home pages, avatars, product images, and important entry icons need an initial visual-anchor decision. If the region establishes page intent, explains state, carries recommendations, or displays product objects, plan a media slot by default.
+
+Asset order:
+
+1. `references/assets/card-illustration-library.md`
+2. UD illustrations / user-provided outlined icon manifest
+3. Product assets or user-provided images
+4. `generated_bitmap`
+
+Whenever media is planned, first read `references/assets/card-illustration-library.md` and write `library_lookup`. If the library already matches semantically and is accessible, do not generate imagery. Generated imagery only creates an independent visual element inside the media slot. It must match the current module theme and feel polished, minimal, and light. It may become a local visual focus, but must not look heavy.
+
+## Fallback Writing Pattern
+
+```md
+ud_control_coverage:
+- detected: customer list
+  follow_ud_style: Table
+  custom_allowed: false
+- detected: welcome banner layout
+  follow_ud_style: Card + custom media slot
+  custom_allowed: true
+  reason: business composition and image slot need custom layout; inner CTA follows UD-style button styling.
+```
+
+## Review Questions
+
+- Is this element a command action, or an entry into an object / workflow?
+- Have visible system controls followed UD visual language, states, and semantics?
+- Does the custom area only handle composition and layout?
+- Are entry items left-aligned and easy to scan?
+- Does the media have business responsibility and a clear source?

package/miaoda/lark-design-prototype/references/design-quality-checklist.md

@@ -0,0 +1,156 @@
+# Design Quality Checklist
+
+Use this checklist before final delivery. The focus is user-visible quality: native Feishu feel, primary flow, UD-style control usage, responsiveness, and visual polish.
+
+## System Fit
+
+- A lightweight `lark_style_recipe` has been formed, covering surfaces, whitespace, radius, borders, shadows, typography, controls, and media.
+- Figma / screenshot tasks have recorded `source_layout_evidence`.
+- Screenshot restoration has recorded `source_viewport_contract` before implementation.
+- Recognizable system controls follow UD visual language, states, and semantics first, or there is a clear custom reason.
+- Custom areas only handle composition, layout, media slots, and one-off business structures.
+- Custom areas and UD-style controls share the same visual language.
+- Cases are only low-weight references and do not override user input or source evidence.
+
+## Product Quality
+
+- The page directly supports the primary task, and the first screen identifies product identity and key content.
+- When the user request is vague, the page only fills core content and a small set of samples. The first screen usually has 2–3 visible content groups and does not actively fill the whole page.
+- Information hierarchy is clear, and primary and secondary actions are distinct.
+- Except for Hero, floating layers, navigation, and single detail cards, content sections have external headers.
+- Repeated rows, cards, entries, and controls share structure.
+- Button is used for command actions; entries, apps, recommendations, and object jumps use Card / List row patterns.
+- Hero appears only when the first glance needs to explain page intent, welcome, smart suggestions, high-value summaries, or empty-state guidance.
+- Navigation items, quick entries, app entries, recommendation entries, list rows, and summary rows default to left alignment.
+- When top-nav or side-navigation is matched, `side-nav-primary` or `top-nav-primary` has been chosen, and the two shell patterns are not mixed. Side navigation uses a near-white neutral background and selected state uses neutral fill with 500 text weight, not light-blue fill by default.
+- Form, approval, settings, and detail-edit pages with top bars have a clear `top_nav_policy`: the bar identifies product / space and low-emphasis utilities, while business actions sit in the page title or primary task area unless source evidence says otherwise.
+- Right auxiliary rails have a clear helper role. They explain rules, approval flow, permissions, risk, or contextual help, and the main task still remains understandable without the rail.
+- Required states such as loading, empty, disabled, error, success, and selected exist.
+- Visible controls are interactive or explicitly recorded as static display.
+- Page-level search sits at the leftmost position of the top-nav right tool button group; content sections only keep search with a clearly local scope.
+
+## Visual Quality
+
+- Overall feel matches polished, minimal, clean, tidy, low-density, and reliable.
+- The page reduces meaningless dividers through large whitespace and module titles.
+- Blue and other accent colors appear only for primary actions, links, focus, current state, real status, or a small amount of brand identification. They do not decorate ordinary cards, icon matrices, category tags, KPIs, or large backgrounds.
+- First-screen accent-color budget is restrained: usually one primary filled button, one current state, and necessary real-status feedback. Avatars, icon backgrounds, entry cards, ordinary tags, KPI containers, and decorative areas do not use high-saturation categories.
+- Page UI uses no gradients. Backgrounds, Hero backing, cards, buttons, tags, icon backgrounds, borders, dividers, masks, and decorative blocks do not use `linear-gradient`, `radial-gradient`, `conic-gradient`, or gradient image masks.
+- Default body text, descriptions, table content, and card descriptions stay 400; the same list, table, card, or navigation group does not contain multiple bold text layers.
+- Form and right-rail pages show an explicit emphasis budget in the final result: one page-level 600 title, limited 500 section / label / selected-state text, and 400 body, helper, button, link, metadata, and bullet text by default.
+- Table body stays 14px / 22px / 400. Customer names, object names, amounts, owners, times, and action links are not bold.
+- Table cells stay single-line. Long text uses ellipsis, column-width adjustment, tooltip, or detail drawer. There is no stacked two-line information.
+- Module titles are not wrapped inside bordered content containers. Borders only wrap tables, lists, card grids, or business content.
+- Large pages and workspaces (body / app-root / main-workspace / main-content / right content area) prefer white or nearly white `bg-body`; light gray is only for low-emphasis shells, side navigation, or local backing surfaces.
+- Sidebars, backing areas, and secondary surfaces are low-presence and do not become obvious gray blocks.
+- 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.
+- Ordinary business cards, Hero, metric cards, quick entries, table containers, and right summaries have no shadows.
+- Borders are light; regular business surfaces use 0.5px `line-border-card`.
+- Radius family is stable within the same local area; regular cards are about 8px.
+- Font sizes mainly use 12px, 14px, and 16px; large titles stay restrained.
+- Icon stroke, size, family, version, shape, source visual type, and semantics follow `references/icon-semantics.md`. Page UI icons are traceable to catalog retrieval, regular page UI usually uses v2 outlined when semantically suitable, and file-type, source-restoration, `source-filled`, `source-colorful`, and brand-colorful usage stay consistent within the same explicit area.
+- top-nav tool icons are consistent in size, usually 28px container + 20px linear icon. side-navigation row height, icons, labels, 2px item vertical spacing, and selected state are stable.
+- top-nav text entries such as help, records, and settings are low-emphasis, usually 14px / 22px / 400. The top bar does not duplicate the page title or carry oversized product identity.
+- Media has responsibility and source. When a visual anchor is needed, `library_lookup` is recorded; there are no gray boxes or meaningless images.
+- Generated images serve only the current media slot, match the current module theme, feel polished and light, and do not generate a full page UI, complete dashboard, or browser shell.
+- When Hero uses a visual anchor, it has first matched the illustration library, UD / product assets, or recorded generated-image fallback.
+- When Hero, welcome areas, recommended content, product entries, or empty states carry first-glance explanation, illustrations, thumbnails, product images, File v2 file icons, or generated-image fallback are planned. They are not replaced by pure text and outlined icons.
+- Quick entries, app entries, and lightweight recommendation entries may use low-saturation, low-opacity blue fills in icon containers, with a consistent group strategy and no high-saturation icon matrix.
+
+## Layout And Responsiveness
+
+- Page body uses responsive document flow and does not copy full-page Figma coordinates.
+- The main workspace uses responsive width and fills the available space after the navigation shell. Workspaces, tables, boards, CRM, admin pages, and data pages do not apply a fixed max width to the whole `main-workspace` / `main-content`.
+- Max reading width is only for local reading areas such as long-form text, settings forms, and detail descriptions.
+- The page follows the 4px base grid; main padding, gaps, column widths, radius, and container offsets use multiples of 4px or page-level variables.
+- Page title, module title, Hero, quick entry, card grid, table container, and right rail align to the same content container line. No single module relies on temporary `margin-left`, temporary `width`, or offsets for alignment.
+- Responsive columns use stable tracks, such as main column `minmax(0, 1fr)`, right auxiliary rail 320–384px, and 24px side gap. The right rail merges into the main flow at narrow widths.
+- First-level content groups use about 40px vertical spacing.
+- Toolbars, card grids, columns, and entry groups use stable gaps and column widths. Hover, selected, loading, and dynamic text do not cause layout jumps.
+- Table row height is stable. Hover, selected, loading, edit state, and long-text ellipsis do not change row height.
+- Single cards, summary blocks, and right panels do not stack too many fields; information presentation feels spacious.
+- Right helper rails in forms use a quiet pattern: plain helper rail, one light panel, or drawer-on-demand. They do not become a stacked card wall.
+- Quick entries and lightweight recommendation entries use equal height within the same row. The parent uses `grid-auto-rows: auto`, and cards in the same row take the height of the tallest card in that row. Short-copy entries do not become uneven by independent auto height, and they also do not create obvious bottom whitespace due to fixed height or whole-group large height.
+- KPIs, lists, recommendations, right-side insights, and quick entries can explain their source or primary-task value. Under vague requests, table / list samples stay within 5–8 rows, card samples within 3–4 items, and KPIs within 1–3 items while serving the primary task.
+- When title areas contain search, filters, Select, Tabs, or buttons, they can wrap or stack at narrow widths.
+- Filters, Tabs, view switches, and local actions align as one toolbar group. At standard width, Select / DatePicker does not stretch across the whole row.
+- When space is tight, filters collapse into IconButton + Dropdown / Popover / Drawer instead of a long selector occupying one row.
+- Long text in any language is not squeezed into character-by-character, vertical, or single-character columns.
+- The right auxiliary rail can merge into the main content flow at narrow widths.
+- side-navigation can shrink to a 64–72px icon rail at `narrow`; text navigation does not degrade into initials or single characters. `compact` has a drawer, top entry, or bottom entry plan.
+- The compact viewport can still identify the current page, primary action, and main content.
+
+## Figma / Screenshot Restoration
+
+- Source region order, primary / secondary relationship, density, and component boundaries are preserved.
+- Browser viewport matches `source_viewport_contract`.
+- Scale check: the restored page feels correctly sized at normal browser zoom based on stable anchors such as sidebar width, avatar size, header height, input height, and body text.
+- auto layout, padding, gap, constraints, component instances, and state evidence have been converted into responsive layout relationships.
+- Top bars, navigation, tabs, list rows, avatars, badges, message cards, and floating actions have no visible collisions.
+- UD-style control patterns cover Button, Input, Select, Tabs, Table, Menu, Drawer, Dialog, Tag, Badge, Avatar, and other system controls first.
+- When the UD default visual does not fully match, tokens, size, outer layout, and local CSS are used first.
+- Custom local implementation is used only when it clearly cannot satisfy source evidence.
+
+## Hard Failures
+
+The following issues must be fixed before delivery:
+
+- Core interaction is missing and no static exception is explained;
+- Figma / screenshot restoration lacks source evidence;
+- Screenshot restoration lacks `source_viewport_contract`;
+- Screenshot restoration has obvious collisions in the top bar, navigation, tabs, list rows, avatars, badges, message cards, or floating actions;
+- Standard system controls are widely rendered as unstyled ordinary `div` or native controls;
+- Ordinary business cards, Hero, metric cards, quick entries, table containers, or right summaries use shadows;
+- The page has heavy gray backgrounds, strong borders, or a wall of cards, making Feishu style heavy;
+- Main content area / main-content / right content area uses an obvious light-gray large background to back the whole workspace instead of a white or nearly white page base;
+- Sidebar background is an obvious gray block, or selected state defaults to light-blue fill / brand-blue text;
+- Blue or other accent colors are used for ordinary decoration, icon matrices, category tags, large KPI backgrounds, or multiple non-primary status areas;
+- The first screen simultaneously uses blue, success, warning, danger, or purple to distinguish ordinary entries, KPIs, avatars, tags, and decoration, causing high visual noise;
+- Page UI uses gradients, including gradient backgrounds, Hero backing, buttons, cards, tags, icon backgrounds, borders, masks, or decorative blocks;
+- Filled icons appear without source evidence or an explicit `source-filled` strategy, or page UI icons bypass catalog retrieval by using AI-drawn icons, emoji, text characters, CSS / canvas drawing, hand-written SVG, or a third-party icon library while the catalog has usable icons;
+- Colorful icons are used as ordinary decoration without file-type, source-restoration, or brand-identity responsibility;
+- An explicit icon area mixes family, v2 / non-v2 version, File v2 colorful round / normal shape, bitmap icons, emoji, text characters, CSS / canvas drawing, or hand-written SVG shapes;
+- Icon colors lack action, status, current, disabled, emphasis, file-type, source-restoration, or brand-identity semantics. Same-group navigation, toolbar, entry cards, or table row actions mix multiple high-saturation colors;
+- top-nav avatars, table avatars, and member avatars use high-saturation colors and distract from page hierarchy;
+- Titles, descriptions, tags, and numbers are all bold in the same list, table, card, or navigation group, causing hierarchy confusion;
+- Form pages have no emphasis budget, causing labels, descriptions, buttons, helper text, and approval steps to all appear bold;
+- Table body contains bold customer names, bold amounts, bold owners, bold times, or bold action links, making row information too heavy;
+- Table cells contain two-line text, primary / secondary titles stacked vertically, or customer name plus industry in two lines, reducing table scan efficiency;
+- The page has gray backing with white cards, white cards with gray blocks, or gray blocks with smaller cards, making surface hierarchy dirty;
+- The page visibly breaks the 4px base grid, with random spacing, chaotic column widths, misaligned module left edges, or interaction states that cause layout jumps;
+- Page title, module title, Hero, quick entry, card grid, table container, or right rail does not share the same content container line and relies on temporary `margin-left`, width, or offset alignment;
+- Key layout values contain many non-4px multiples, or page-level spacing / grid variables are not reused, making module rhythm inconsistent;
+- Workspaces, tables, boards, CRM, admin pages, or data pages apply a fixed max width to the whole main workspace, causing wasted wide-screen space, an uncentered right workspace, or cramped content;
+- Non-exception content sections lack titles, or section titles are wrapped inside bordered containers;
+- Vague user requests proactively generate many unsupported modules, metrics, lists, or right-side panels;
+- Vague user requests show more than 3 visible content groups on the first screen, or simultaneously include a KPI wall, long list, right-side insights, recommendations, recent visits, quick entries, and multi-level navigation;
+- Quick entries, app entries, recommendation entries, or navigation items are centered as a whole, harming scanning;
+- Quick entries use outline Buttons instead of entry cards or list rows;
+- Sidebar navigation items use centered Button styling, or collapsed state compresses text navigation into initials, single characters, or meaningless abbreviations;
+- Navigation items in the same sidebar group touch vertically and lack 2px vertical spacing;
+- top-nav tools mix text-character icons with SVG / UD icons, or a search input and search icon button both appear;
+- top-nav duplicates the page title, uses oversized logo / product identity, makes utility text heavy, or places large business primary actions in the bar without source evidence;
+- Right helper rails use strong stacked card frames, shadows, large titles, bold body text, or high-saturation decoration, causing the rail to compete with the form;
+- `top-nav-primary` or `side-nav-primary` is matched but navigation background, start position, or backing relationship from the other mode is mixed in;
+- Page-level search appears inside a content section, or is not placed at the leftmost position of the top-nav right tool group;
+- Filter controls use full-row width, splitting filters and Tabs into loose rows;
+- Long text is squeezed into character-by-character, vertical, or single-character columns;
+- The page depends on a whole-page fixed canvas size;
+- A planned media slot has no real asset, lacks `library_lookup`, or generated imagery becomes a full page UI;
+- Hero, welcome area, recommended content, product entry, or empty state carries visual explanation but has no media plan and no reason for no-media;
+- Generated imagery is unrelated to the current module theme, or its visual weight overpowers the title, main content, and actions;
+- Quick entries or lightweight recommendation entries in the same row have uneven heights because every card auto-sizes independently;
+- Quick entries or lightweight recommendation entries use fixed height, excessive `min-height`, `aspect-ratio`, `grid-auto-rows: 1fr`, `grid-auto-rows: minmax(...)`, `place-items: center`, or fixed height classes such as `h-24 / h-28 / h-32`, causing all rows to be stretched or short title / description cards to show obvious bottom whitespace;
+- Case rules override user input, Figma / screenshot evidence, or a reasonable current composition.
+- Table directories, settings, audits, approval details, member permissions, or strong operation forms add a marketing-style Hero without evidence.
+
+## Report Format
+
+```md
+summary:
+passed:
+warnings:
+hard_failures:
+verification:
+remaining_risks:
+```

package/miaoda/lark-design-prototype/references/form-shell-patterns.md

@@ -0,0 +1,77 @@
+# Form Shell Patterns
+
+Use this reference only for approval forms, settings forms, detail-edit pages, top bars, right helper rails, or tasks that mention weak Feishu / Lark shell feeling. Keep the main skill lightweight by loading this file only when these regions affect the page quality.
+
+## Top Navigation
+
+Top bars in form and approval tools should feel like a product shell, not a marketing header.
+
+- Height: 56-64px. Use 64px for `top-nav-primary`; use 56px for compact tool pages when source evidence supports it.
+- Surface: `bg-body` with a 0.5px weak bottom divider. Avoid shadow, gray backing, or rounded shell treatment.
+- Left region: app icon or product mark plus product / space name. Keep it compact, left aligned, and vertically centered. Product name usually uses 16px / 24px / 500.
+- Right region: low-emphasis entries such as help, records, settings, notification, and avatar. Text entries default to 14px / 22px / 400; the current entry may use 500.
+- Business actions such as submit, save, create, approve, reject, and export belong in the page title area or primary task area by default. Put them in the top bar only when source evidence clearly places them there.
+- Do not repeat the same page title in both the top bar and the page header. The top bar identifies the product or space; the page header identifies the current task.
+- Avoid oversized logos, 600-weight nav labels, high-saturation avatar fills, large primary buttons, duplicated search entry, and empty wide top bars with only two text links.
+
+## Page Title And Actions
+
+Form pages should open with a concise task header.
+
+- Breadcrumb or location text: 14px / 22px / 400, `text-caption`.
+- Page title: 24px / 36px / 600 for the only page-level title.
+- Description: 14px / 22px / 400, `text-caption`, up to two lines.
+- Primary and secondary actions sit on the right side of the title area at standard width, then wrap under the title on narrow width.
+- Button labels stay 14px / 22px / 400. Priority comes from fill, order, and placement.
+
+## Right Helper Rail
+
+Right rails in forms are auxiliary. They should reduce hesitation without competing with the form.
+
+- Use a right rail only when it explains form rules, approval flow, permissions, risk, or contextual help that affects the current task.
+- Common width: 320-360px. Use 384px only for richer details with proven need. Gap from main content: 24px.
+- Prefer one light rail group or two small groups. Avoid a stacked card wall.
+- Surface choices:
+  - `plain_helper_rail`: no full card frame; use section titles, whitespace, and weak dividers.
+  - `light_panel_rail`: 0.5px `line-border-card`, 8px radius, 16-20px padding, no shadow.
+  - `drawer_on_demand`: use when helper content is long or rarely needed.
+- Title: 14px / 22px / 500 or 16px / 24px / 500 only when the rail has one main group.
+- Body, bullets, metadata, helper links, and approval descriptions: 12-14px / 20-22px / 400.
+- Number chips and step indicators should be small, neutral, and quiet. They should not become colorful KPI badges.
+- At `narrow`, merge the rail below the form. At `compact`, place helper content after the primary form or behind a help entry.
+- Avoid heavy borders around every rail group, big section titles, bold bullet text, strong gray blocks, shadows, decorative icons, and high-saturation status colors unless they express real state.
+
+## Emphasis Budget
+
+Use font weight to create one clear reading path.
+
+| Region | Default treatment |
+| --- | --- |
+| Page title | 24px / 36px / 600, only one per page |
+| Section title | 16px / 24px / 500 |
+| Form label | 14px / 22px / 500 |
+| Form value / input text | 14px / 22px / 400 |
+| Button label | 14px / 22px / 400 |
+| Right rail title | 14px / 22px / 500 |
+| Right rail body | 12-14px / 20-22px / 400 |
+| Approval step owner | 14px / 22px / 500 |
+| Approval step description | 12px / 20px / 400 |
+
+One local information group should usually contain only one 500-weight layer. Do not bold title, description, bullet body, step owner, metadata, and action text at the same time.
+
+## Approval Form Pattern
+
+Use this pattern for approval, permission, access, procurement, leave, reimbursement, and similar form pages.
+
+```md
+approval_form_page:
+  shell: compact top bar with product / space identity and low-emphasis utility entries
+  header: breadcrumb + page title + description + page-level actions
+  main: external section titles + light form surfaces, using UD controls
+  rail: helper rules and approval path with low emphasis
+  primary_action: page title area, not top nav by default
+  no_hero: true
+  no_card_wall: true
+```
+
+Check that the page still works without the rail. If the main task becomes unclear without the rail, move essential guidance into the form itself.

package/miaoda/lark-design-prototype/references/icon-semantics.md

@@ -0,0 +1,237 @@
+# Icon Semantics
+
+Icons support functionality, identity, and source restoration. Choose icons from the catalog, keep choices traceable, and avoid decorative icon noise.
+
+## Contents
+
+- Icon Source And Query
+- Catalog Retrieval Requirement
+- Selection Order
+- V2 Priority
+- Area Consistency
+- Natural-Language Page Generation
+- Figma And Screenshot Restoration
+- File V2 Colorful
+- Brand Logo Rules
+- Icon Color Semantics
+- Size Hierarchy
+- Lightweight Checks
+- Fallback
+
+## Icon Source And Query
+
+Use the versioned public catalog on demand:
+
+```txt
+https://lf3-static.bytednsdoc.com/obj/eden-cn/pshi/lark-design-prototype/1.0.4/db71a6cd-33f97519-0d446cd5/icons.catalog.json
+```
+
+The catalog is an array of categories. Each category usually contains `icons.colorful`, `icons.filled`, and `icons.outlined`. These are the real catalog families. Skill-level visual types such as `v2-outlined`, `non-v2-outlined`, `file-v2-colorful-normal`, `file-v2-colorful-round`, `brand-colorful`, `source-outlined`, `source-filled`, and `source-colorful` are derived from the icon name, source evidence, and usage.
+
+Use `node scripts/icon-query.mjs` instead of printing the raw catalog. It fetches the public catalog and verifies the pinned SHA-256 before parsing it; keep output to 3-5 candidates per intent. A user- or project-provided catalog can be supplied with `--catalog <catalog.json|url>`. If the public catalog is unavailable and no trusted override exists, record the failure and use text, Avatar, official media, or an icon-free structure rather than inventing an icon.
+
+Assemble final SVG URLs in this format:
+
+```txt
+https://cdn-tos-cn.bytedance.net/obj/archi/ee/es-design-base/svgs/{name}.{hash}.svg
+```
+
+When a dark interface needs a dark-specific icon asset and the entry has `darkHash`, use `darkHash` instead of `hash`.
+
+## Catalog Retrieval Requirement
+
+All page UI icons must go through catalog retrieval before implementation. Query `node scripts/icon-query.mjs`, choose a catalog entry, and use the returned `name`, `hash`, family, visual type, and final URL. This applies to navigation icons, toolbar icons, quick-entry icons, table actions, status helpers, file-type icons, brand logo slots, and source-restoration icon replacements.
+
+Do not draw page UI icons yourself. Avoid inline SVG path drawing, CSS-only shapes, canvas-drawn symbols, emoji, text characters, third-party icon libraries, or generated bitmap icons as replacements for catalog icons.
+
+If catalog retrieval has no suitable match:
+
+1. try a nearby v2 match in the same area strategy;
+2. use the area-level fallback to non-v2 when needed;
+3. use text, Avatar, official illustration, product image, card media, or an icon-free structure.
+
+Do not invent a new icon name or create an AI-drawn icon to fill the gap. Generated bitmap imagery may appear in media or illustration slots, but it must not replace functional page UI icons.
+
+## Selection Order
+
+Before selecting individual icons, decide the area-level strategy:
+
+```md
+icon_area_plan:
+- area: sidebar | top_toolbar | quick_entry | file_list | table_row_actions | brand_header
+  source_visual_type: unknown | outlined | filled | colorful
+  visual_type: v2-outlined | non-v2-outlined | file-v2-colorful-normal | file-v2-colorful-round | brand-colorful | source-outlined | source-filled | source-colorful
+  family: outlined | filled | colorful
+  version: v2 | non-v2 | brand
+  shape: none | normal | round
+  fallback: keep the whole area consistent before changing individual icons
+```
+
+Then choose individual icons in this order:
+
+1. Exact source icon name, family, version, and shape when restoring Figma or screenshots.
+2. Same source visual type when the source is identifiable: `source-outlined`, `source-filled`, or `source-colorful`.
+3. Same area `visual_type`, with v2 candidates first when the strategy is outlined or file colorful.
+4. Same area family and shape with a non-v2 fallback when v2 semantics are not suitable.
+5. Text, Avatar, official illustration, product image, card media, or an icon-free structure.
+
+Do not invent icon names. Missing an icon is better than using a semantically wrong icon.
+
+## V2 Priority
+
+Prefer v2 icons for both outlined and colorful usage.
+
+- Regular UI icons first query `outlined` candidates whose names contain `-v2_` or `-v2-` when such candidates semantically match the intent.
+- File-type colorful icons first query File v2 colorful names, such as `icon_file-doc-v2_colorful`, `icon_file-sheet-v2_colorful`, `icon_file-round-doc-v2_colorful`, and similar entries.
+- Source-restoration filled icons use catalog `filled` when the source clearly uses filled glyphs. Do not force a filled source area into v2 outlined just to satisfy regular UI defaults.
+- If a single item lacks a strong v2 match, try a nearby v2 semantic match in the same area before falling back.
+- If several important items in the same area lack suitable v2 matches, downgrade the whole area to the matching non-v2 type.
+- Do not mix v2 outlined and non-v2 outlined inside the same navigation group, toolbar, quick-entry group, table row action area, or file-list group.
+
+Brand logo icons are explicit brand assets and do not follow v2 priority.
+
+## Area Consistency
+
+The same explicit area must keep one icon strategy. Common areas include navigation groups, top toolbar tools, filter/action toolbars, quick-entry groups, app-entry groups, table row actions, recent document lists, attachment lists, file directories, and brand headers.
+
+Within one area, keep these properties consistent:
+
+- family: do not mix `outlined`, `colorful`, `filled`, bitmap, emoji, character icons, or hand-written SVG shapes;
+- version: do not mix v2 and non-v2 when the visual type is outlined;
+- shape: do not mix File v2 colorful normal and round shapes;
+- size: keep icon size consistent within the same toolbar, row, or menu;
+- color role: use semantic hierarchy instead of random category colors.
+
+Different areas may use different strategies. For example, a sidebar can use `v2-outlined`, a recent file list can use `file-v2-colorful-normal`, and a product header can use `brand-colorful`.
+
+## Natural-Language Page Generation
+
+For natural-language tasks, choose icons by catalog `description` before relying on name similarity. Compare:
+
+- user task and module intent;
+- action semantics, such as search, filter, create, export, upload, approve, or delete;
+- object semantics, such as document, sheet, calendar, meeting, mail, task, folder, or AI;
+- state semantics, such as selected, disabled, warning, success, unread, locked, or offline;
+- product domain and Chinese / English synonyms.
+
+Regular page UI defaults to `v2-outlined` when matching candidates exist. Navigation, toolbars, search, filter, refresh, settings, more, upload, download, expand / collapse, entry cards, table row actions, status helpers, category helpers, and ordinary object types use outlined icons unless the area is a file-type group, brand identity, or screenshot source restoration.
+
+## Figma And Screenshot Restoration
+
+Source evidence has priority. If the icon can be identified from layer name, component name, export name, visual shape, or nearby text, reproduce the same catalog `name`, family, version, and visual type.
+
+First classify each explicit icon area by source visual type:
+
+- `source-outlined`: strokes, hollow shapes, neutral line icons, or toolbar glyphs with visible stroke structure;
+- `source-filled`: solid silhouettes, filled tab icons, filled status glyphs, or source icons whose main shape is filled rather than stroked;
+- `source-colorful`: multicolor icons, product-color icons, file-type colorful icons, brand assets, or colorful circular / normal catalog icons.
+
+Use the matching query style for the area:
+
+```txt
+node scripts/icon-query.mjs --style source-outlined --query "<intent>"
+node scripts/icon-query.mjs --style source-filled --query "<intent>"
+node scripts/icon-query.mjs --style source-colorful --query "<intent>"
+```
+
+Do not convert a clearly filled or colorful source area to outlined only because regular generated pages default to outlined. If one icon in an area has unclear source type, infer from neighboring icons in the same area, then keep the area consistent.
+
+When the source icon is colorful:
+
+- for screenshot restoration, when source icons are visibly colorful in an area, preserve colorful catalog icons for that area unless the source is unclear or no suitable catalog match exists;
+- keep colorful if the source role is a brand logo, file-type identifier, or clearly colorful product/source icon;
+- preserve the same area shape and type before selecting nearby alternatives;
+- choose the closest same-type catalog entry by `description` when the exact name is missing;
+- record `fallback_reason` when the selected icon differs from the source visual type.
+
+When the source icon is filled:
+
+- preserve filled catalog icons for the whole area when the source glyphs are visibly solid;
+- choose the closest `filled` catalog entry by `description`, nearby text, and object / action semantics;
+- keep size, color role, and filled-vs-outlined family consistent across the same area;
+- record `fallback_reason` if no suitable filled match exists and the whole area falls back to outlined.
+
+If the source is unclear or the area cannot stay consistent, downgrade the whole area to a consistent outlined strategy or use an icon-free structure.
+
+## File V2 Colorful
+
+File v2 colorful identifies file types. It is appropriate for file lists, recent documents, document cards, attachment lists, templates, and file directories that need to distinguish doc, sheet, slide, base, mindnote, file, folder, and similar object types.
+
+Before use, record in `icon_plan`:
+
+- `usage: file_type_identification`;
+- `visual_type: file-v2-colorful-normal` or `file-v2-colorful-round`;
+- catalog `family: colorful`;
+- file type;
+- shape: `normal` or `round`;
+- matched `name`, `hash` / `darkHash`, and final URL.
+
+Do not use File v2 colorful for ordinary navigation, toolbars, entry categories, generic statuses, or decoration. If shape consistency cannot be confirmed, choose outlined or an icon-free structure.
+
+## Brand Logo Rules
+
+Brand and product identity positions may use approved colorful logo assets:
+
+- Use `icon_feishu-logotype-zh_colorful` for Chinese Feishu brand positions.
+- Use `icon_feishu-logotype-en_colorful` for English Lark / Feishu brand positions.
+
+These icons are `brand-colorful`. They are allowed in top brand areas, login / welcome areas, official brand pages, and product identity slots. Do not use them as ordinary navigation icons, list icons, status icons, or decorative marks.
+
+Record in `icon_plan`:
+
+- `usage: brand_identity`;
+- language choice: `zh` or `en`;
+- selected `name`, `hash` / `darkHash`, family, and final URL.
+
+## Icon Color Semantics
+
+Icon color follows responsibility:
+
+- default icon: `icon-n2`;
+- current item, high emphasis, or current page anchor: `icon-n1`;
+- low-emphasis helper: `icon-n3`;
+- disabled state: `icon-disabled`;
+- icon inside filled primary button: `primary-on-primary-fill`;
+- primary action, link, focus, or current state on neutral surface: `primary-content-default`;
+- danger, success, warning, and info icons: functional colors only for real statuses or real risks.
+
+Navigation items, entry cards, toolbars, table row actions, category tags, ordinary object types, helper icons near avatars, and decorative positions default to neutral icon colors. Do not use brand blue, green, orange, red, or purple to categorize every entry in the same group. File v2 colorful uses its own file-type color and should not receive extra high-saturation or status colors.
+
+## Size Hierarchy
+
+- 12px: dense inline metadata.
+- 14px: compact controls and menu rows.
+- 16px: standard actions.
+- 20px: toolbar or empty-state helpers.
+- 24px: prominent product objects or onboarding helpers.
+- top-nav right tool button: 28px container + 20px linear icon; dense toolbars may use 18px icons, but the same group must be consistent.
+- top-nav left menu / collapse control: 24-28px container + 18px icon.
+- expanded side-navigation row: 18-24px icon or avatar container; regular product icons prefer 18px, avatars may use 24-28px.
+- collapsed side-navigation rail: 40px row, centered icon, usually 18px icon or 24px avatar container.
+- account avatar entry: 32px.
+
+Judge icon size together with row height and button height. Icons should not be enlarged alone and create a loose, heavy feel.
+
+## Lightweight Checks
+
+Keep checks light. They should catch obvious problems, not perform full semantic review.
+
+Useful checks:
+
+- icon URLs follow the catalog CDN pattern or a deliberate local asset path;
+- page UI icons are traceable to catalog retrieval and do not use AI-drawn, CSS-drawn, canvas-drawn, emoji, text-character, third-party, or hand-written SVG replacements;
+- `filled` appears only when source evidence or an explicit `source-filled` area strategy supports it;
+- explicit areas marked or named as navigation, toolbar, quick entry, file list, table row actions, or brand header do not mix major family / version / shape;
+- brand positions use the approved Feishu logotype assets when Feishu / Lark identity is required.
+
+Avoid heavy checks:
+
+- do not require every icon to include a long semantic proof;
+- do not force every icon to be v2 when the v2 candidate is semantically weak;
+- do not run complex DOM inference to guess every icon area;
+- do not block screenshot restoration just because the source colorful icon is not a file-type icon;
+- do not require a full icon audit for small pages with only one or two simple icons.
+
+## Fallback
+
+If the catalog has no suitable icon, prefer text, Avatar, an official illustration, product image, card media, or an icon-free structure. Use non-v2 only after v2 candidates fail semantic matching. Use area-level fallback so one group stays visually coherent.