diff --git a/.agents/skills/dsh-client-ui-ux/SKILL.md b/.agents/skills/dsh-client-ui-ux/SKILL.md index 6ab8f1e5cb..de9f359f89 100644 --- a/.agents/skills/dsh-client-ui-ux/SKILL.md +++ b/.agents/skills/dsh-client-ui-ux/SKILL.md @@ -56,7 +56,7 @@ Read alignment and spacing before layout changes; otherwise select the applicabl ## Reuse before adding -Extend existing components, containers and interactions when the capability fits. Register right-sidebar content in the existing sidebar. Follow [icon reuse](../dsh-ui-icons/SKILL.md#reuse-existing-icons-first). Before restructuring, read [client instructions](../../../packages/client/AGENTS.md) and [client defensive patterns](../../../docs/defensive-patterns/client-components.md) for component/state ownership and layering. +Extend existing components, containers and interactions when the capability fits. Register right-sidebar content through a slot in the existing sidebar; do not create a separate sidebar. Follow [icon reuse](../dsh-ui-icons/SKILL.md#reuse-existing-icons-first). Before restructuring, read [client instructions](../../../packages/client/AGENTS.md) and [client defensive patterns](../../../docs/defensive-patterns/client-components.md) for component/state ownership and layering. ## Visual foundation @@ -64,7 +64,7 @@ Extend existing components, containers and interactions when the capability fits - Verify colors in light and dark themes; keep ink/background pairs readable, especially dimmed text. - Feature CSS you add or change uses **font weight ≤500**; emphasize with size or ink. ui-theme markdown typography tokens are the exception. - Use theme typography roles, then the page's scale, then a comparable page's size/spacing ratios. Do not invent a size for a single element. Peers share sizes; keep the scale small (13px is the established row/detail size). -- Apply alignment and icon rules to icon/text relationships. +- Apply [alignment](../dsh-ui-alignment/SKILL.md) and the [same-foreground rule](../dsh-ui-icons/SKILL.md#placement-and-use) to icon/text relationships, including value chevrons and search prompts. ## Component geometry diff --git a/.agents/skills/dsh-ui-alignment/SKILL.md b/.agents/skills/dsh-ui-alignment/SKILL.md index 25b1522462..fc5e0efd4a 100644 --- a/.agents/skills/dsh-ui-alignment/SKILL.md +++ b/.agents/skills/dsh-ui-alignment/SKILL.md @@ -7,7 +7,7 @@ description: Design or review DSH shared text columns, icon/label placement, tre Apply within the [UI development loop](../dsh-client-ui-ux/SKILL.md#required-review-loop). Align comparable peers, including slots for optional icons and actions. -### Layout structure first, visual calibration second +## Layout structure first, visual calibration second Distinguish click target, painted button, complete icon box and drawn contour. Intentional icon whitespace belongs to the layout box; do not remove it merely because painted pixels miss a guide. Enlarging a target must not move that box. Check containers, slots, columns, gaps and unintended overrides before optical corrections. Neither matching CSS boxes nor aligning every painted contour alone establishes balance. @@ -15,9 +15,9 @@ A glyph inconsistent across uses belongs to its icon owner. A composition-specif Inline SVG `vertical-align: middle` follows font baseline/x-height, not visible text center. Check font, size, line height and icon box across CJK, Latin, monospace and wrapping. Do not make multiline links unwrappable just to center an icon. -### Choose both the object and the axis +## Choose both the object and the axis -Name the aligned object and reference container. Equal padding need not align text starts; equal SVG dimensions need not align visible centers. +Name the aligned object and reference container. Equal padding need not align text starts; equal SVG dimensions need not align visible centers. For a close control beside footer actions, explicitly choose the control edge or complete icon-box edge; do not switch between them while measuring. | Alignment | Use it for | Judge the actual relationship | Common mistake | |---|---|---|---| @@ -30,6 +30,8 @@ Name the aligned object and reference container. Equal padding need not align te For Chinese/English navigation, identify leading icon centers, text starts and trailing controls by role. Headings, avatars and expandable search may differ. Continue axes only where the composition establishes them, including shared plugin reading edges even when hover paint extends beyond them, and conversation/right-sidebar header heights and baselines. +For a trigger and its menu, or search field and result rows, compare the complete text inset: outer padding, borders, leading slot and gap. Different icon sizes can retain one text start. For adjacent statistics, check font family, size, weight and line height together before moving the icon. + Center a button within its own bounds, a welcome group within the main pane, and an empty state within the content remaining below headings/filters. A fixed top margin is not centering. When a short window cannot fit the group, preserve scroll access with a compact top-aligned layout instead of clipping. -Normalize peer control sizes and slots before any necessary small optical offsets; verify comparable uses. Preserve usable hit targets and do not hide inconsistent parent layout with transforms. Check [spacing](../dsh-ui-spacing/SKILL.md) without moving the chosen axes; consult [cases](../../../docs/ui-design-review-cases.md#alignment) for uncertain judgments. +Normalize peer control sizes and slots before any necessary small optical offsets; verify comparable uses. Preserve usable, non-overlapping hit targets and do not hide inconsistent parent layout with transforms. Transparent hit padding can exceed the painted icon slot; check neighboring target edges after tightening a cluster. Check [spacing](../dsh-ui-spacing/SKILL.md) without moving the chosen axes; consult [cases](../../../docs/ui-design-review-cases.md#alignment) for uncertain judgments. diff --git a/.agents/skills/dsh-ui-icons/SKILL.md b/.agents/skills/dsh-ui-icons/SKILL.md index b94a075407..f42277a62d 100644 --- a/.agents/skills/dsh-ui-icons/SKILL.md +++ b/.agents/skills/dsh-ui-icons/SKILL.md @@ -13,7 +13,7 @@ Search the library and comparable UI for the intended meaning and supported vari Draw only when existing artwork cannot express the meaning or the user requests a distinct design. Before drawing, explain the closest alternatives and the unmet meaning or requested design difference. New glyphs require designer approval before landing; requested drafts can be prepared locally. Do not redraw a shared glyph to fix one consumer. -The [primitives catalog](../../../packages/client/ui-primitives/README.md#component-catalog) and icon source own available variants and stroke values; [official artwork](../dsh-official-plugin-artwork/SKILL.md) owns package artwork. +The [primitives icon contract](../../../packages/client/ui-primitives/README.md#controls-and-icons) and icon source own available variants, stroke scaling and menu sizes; [official artwork](../dsh-official-plugin-artwork/SKILL.md) owns package artwork. ## System style @@ -22,6 +22,18 @@ The [primitives catalog](../../../packages/client/ui-primitives/README.md#compon - Default to monochrome outlines inheriting `currentColor`, without gradients, shadows, textures or 3D effects. Preserve intentional fills, status dots, selected marks and knockouts. File, site, plugin and brand artwork retain their own palettes and roles. - Balance structure and whitespace without requiring symmetry; avoid accidental tilt or a top-heavy silhouette. Preserve meaningful direction. Use gaps, overlap, nesting and broken obscured lines to clarify complex meanings; avoid accidental tangencies, dark knots and disappearing gaps at actual size. Add contour detail only when it improves recognition; do not force every subject into a closed outline. +## Optical size and clarity before implementation + +Use the owning control's supported size and weight. [Shared menu sizes and stroke scaling](../../../packages/client/ui-primitives/README.md#controls-and-icons) belong to primitives; [permission triggers](../../../packages/client/ui-permission-presets/README.md) and [settings navigation](../../../packages/client/ui-settings-general/README.md) belong to their feature packages. A reviewed proposal for a larger or heavier trigger is not a statement that every existing consumer already uses it. Compare at the owning control's size, weight, colors and label, using an outlined circle and rectangular control as references. Open silhouettes may need more extent than dense fills; supporting chevrons, handles and dots keep their roles. Do not normalize by ink area or fill every view box. + +A shared view-box change affects every consumer at its own CSS size. Inspect both compact menus and larger icon-only controls; a clearer small chevron can become oversized in a floating button. Adjust a consumer’s supported icon size when needed while retaining its button base and hit target. + +For softness, check CSS dimensions and ancestor transforms, view box and drawing bounds, stroke versus filled contour, device-pixel placement, then color/opacity. Non-16 view boxes are valid; compare identical artwork before attributing sharpness to inline SVG versus sprites. + +Use the [implemented stroke behavior](../../../packages/client/ui-primitives/README.md#controls-and-icons): source stroke widths scale with the SVG viewport, and filled outlines scale as geometry. Do not add non-scaling strokes or convert filled contours during an ordinary placement or reuse fix. A change to that rendering contract belongs to a separately scoped library change with consumer validation; retain intentional silhouettes and knockouts. + +Check straight-stroke edges at actual DPR after all scaling: center and width jointly determine coverage. Integer source coordinates alone do not guarantee crisp edges. Round positioned overlays in device pixels only when layout places otherwise crisp artwork between pixels; preserve anchoring and viewport containment. Keep antialiasing on curves/diagonals; do not globally round paths or use `crispEdges` to hide placement errors. Partial coverage is legitimate for 1.3px strokes. + ## Draw a new icon Establish meaning, placement, actual sizes, peers and states; ask only when missing information changes the design. Produce editable SVG; shared line icons need Regular and Medium variants sharing construction; intentional fill-only variants may share geometry. Tune silhouette, gaps, center and weight at intended size using component/theme conventions, not consumer-specific stroke or scale overrides. @@ -38,22 +50,12 @@ Apply the same system style and verification criteria as new artwork. Inspect SV Distinguish click target, visible button base, icon slot and painted glyph. Equal targets or SVG dimensions do not imply equal optical size; compare silhouette, stroke, whitespace and center beside the label. Fix containers and unintended CSS overrides first. Correct shared artwork only when the imbalance follows it across uses. -An icon and label for one action normally share foreground and state changes. Search icons and placeholders form one prompt; typed text and independent clear actions may differ. Verify opacity, stroke and background in both themes. Status, warning and brand roles may use different colors. Compare native file icons and folder outlines deliberately; do not normalize logos, status dots or decorative illustrations to toolbar icons. +An icon and its associated text for one action, value or input prompt must share foreground color, effective opacity and state changes. This includes submenu value chevrons and search placeholders; inherit the shared role instead of assigning an independent icon token. Typed text and independent clear actions may differ; status, warning and brand roles retain semantic colors. Check computed color and ancestor opacity in both themes. Apply the rule to changed consumers; updating it does not certify untouched UI. Compare native file icons and folder outlines deliberately; do not normalize logos, status dots or decorative illustrations to toolbar icons. -Use the shared Tooltip for unclear icon-only actions and HoverCard for informational content requiring hover or selection. [Responsive UI](../dsh-responsive-ui/SKILL.md) owns mobile tooltips and label collapse. Every right-sidebar tab needs a meaningful icon. Preserve accessible labels and focus; [alignment](../dsh-ui-alignment/SKILL.md) owns positioning and [spacing](../dsh-ui-spacing/SKILL.md) owns gaps. - -## Optical size and clarity before implementation - -Ordinary menus use 14px Regular icons with 1px strokes; compact menus retain 12px. Permission triggers and settings-navigation peers use 16px slots; permission-menu rows retain 14px. Compare at the owning control's size, weight, colors and label, using an outlined circle and rectangular control as references. Open silhouettes may need more extent than dense fills; supporting chevrons, handles and dots keep their roles. Do not normalize by ink area or fill every view box. - -For softness, check CSS dimensions and ancestor transforms, view box and drawing bounds, stroke versus filled contour, device-pixel placement, then color/opacity. Non-16 view boxes are valid; compare identical artwork before attributing sharpness to inline SVG versus sprites. - -Regular strokes stay **1 CSS px**, Medium **1.3 CSS px** across sizes. Use non-scaling strokes, including inline composites. Filled outlines ignore stroke width: convert line contours to real strokes when consistent weight requires it; retain intentional silhouettes and knockouts. - -Check straight-stroke edges at actual DPR after all scaling: center and width jointly determine coverage. Integer source coordinates alone do not guarantee crisp edges. Round positioned overlays in device pixels only when layout places otherwise crisp artwork between pixels; preserve anchoring and viewport containment. Keep antialiasing on curves/diagonals; do not globally round paths or use `crispEdges` to hide placement errors. Partial coverage is legitimate for 1.3px strokes. +Use the shared Tooltip for unclear icon-only actions and HoverCard for informational content requiring hover or selection; prefer these primitives over ad-hoc `title` attributes. [Responsive UI](../dsh-responsive-ui/SKILL.md) owns mobile tooltips and label collapse. Every right-sidebar tab needs a meaningful icon. Preserve accessible labels and focus; [alignment](../dsh-ui-alignment/SKILL.md) owns positioning and [spacing](../dsh-ui-spacing/SKILL.md) owns gaps. ## Verification and handoff For ordinary icon reuse or placement changes, inspect the affected control at its actual size and relevant states; no fixed size/DPR matrix or separate raster report is required. For new or changed artwork, strokes or rendering, compare affected sizes and weights with peers; check DPR 1 and 2 when stroke scaling or pixel placement can change, and both themes when color or optical weight is affected. Keep before/after captures when needed for the change or requested deliverable. Judge recognition, clipping, center, gaps and neighboring text at actual size; enlarged views diagnose pixels only. -After a set-wide change, trace affected families, consumers and weights, including unchanged artwork whose rendering can change. Use unchanged peers for comparison. An explicitly requested full-set review inventories and compares every glyph under matching conditions. Consolidate duplicate artwork only when necessary for the current fix; record unrelated duplicates separately instead of expanding the task. Consult [cases](../../../docs/ui-design-review-cases.md#icon-optics) for uncertain judgments. \ No newline at end of file +After a set-wide change, trace affected families, consumers and weights, including unchanged artwork whose rendering can change. Use unchanged peers for comparison. An explicitly requested full-set review inventories and compares every glyph under matching conditions. Consolidate duplicate artwork only when necessary for the current fix; record unrelated duplicates separately instead of expanding the task. Consult [cases](../../../docs/ui-design-review-cases.md#icon-optics) for uncertain judgments. diff --git a/.agents/skills/dsh-ui-spacing/SKILL.md b/.agents/skills/dsh-ui-spacing/SKILL.md index 1f3cea88c4..0c6bf57613 100644 --- a/.agents/skills/dsh-ui-spacing/SKILL.md +++ b/.agents/skills/dsh-ui-spacing/SKILL.md @@ -19,4 +19,6 @@ When wrapping, metadata, subgroups or independent actions increase complexity, i Judge actual whitespace at normal size, including padding, line-height, glyph whitespace and borders. CSS margin ratios alone do not establish grouping; explanatory labels need one unambiguous owner. For example, declared 16px/8px margins can still leave a heading closer to the preceding content once line-height and container padding are included; compare the rendered gaps rather than adopting that pair as a rule. +When matching two visible gaps, name both pairs of endpoints and include each container’s padding, border and text line box. Equal visible gaps may require unequal margins. A control’s painted edge and a text glyph’s edge are different endpoints; keep that choice stable through review. + Reuse page spacing and [style tokens](../../../docs/web-styling.md), preserve [alignment](../dsh-ui-alignment/SKILL.md) axes, and consult [cases](../../../docs/ui-design-review-cases.md#grouping) for uncertain judgments. This skill defines no numeric scale. diff --git a/docs/assets/ui-design-review/alignment-after.jpg b/docs/assets/ui-design-review/alignment-after.jpg deleted file mode 100644 index 9f80b99401..0000000000 Binary files a/docs/assets/ui-design-review/alignment-after.jpg and /dev/null differ diff --git a/docs/assets/ui-design-review/alignment-before.jpg b/docs/assets/ui-design-review/alignment-before.jpg deleted file mode 100644 index fd01742e45..0000000000 Binary files a/docs/assets/ui-design-review/alignment-before.jpg and /dev/null differ diff --git a/docs/assets/ui-design-review/component-choice-after.jpg b/docs/assets/ui-design-review/component-choice-after.jpg deleted file mode 100644 index 25113fc08d..0000000000 Binary files a/docs/assets/ui-design-review/component-choice-after.jpg and /dev/null differ diff --git a/docs/assets/ui-design-review/component-choice-before.jpg b/docs/assets/ui-design-review/component-choice-before.jpg deleted file mode 100644 index 35fbe5393c..0000000000 Binary files a/docs/assets/ui-design-review/component-choice-before.jpg and /dev/null differ diff --git a/docs/assets/ui-design-review/density-after.jpg b/docs/assets/ui-design-review/density-after.jpg deleted file mode 100644 index d0241c4210..0000000000 Binary files a/docs/assets/ui-design-review/density-after.jpg and /dev/null differ diff --git a/docs/assets/ui-design-review/density-before.jpg b/docs/assets/ui-design-review/density-before.jpg deleted file mode 100644 index b4bf541fcb..0000000000 Binary files a/docs/assets/ui-design-review/density-before.jpg and /dev/null differ diff --git a/docs/assets/ui-design-review/grouping-after.jpg b/docs/assets/ui-design-review/grouping-after.jpg deleted file mode 100644 index 7fe1f8ad51..0000000000 Binary files a/docs/assets/ui-design-review/grouping-after.jpg and /dev/null differ diff --git a/docs/assets/ui-design-review/grouping-before.jpg b/docs/assets/ui-design-review/grouping-before.jpg deleted file mode 100644 index ea5cd8dd31..0000000000 Binary files a/docs/assets/ui-design-review/grouping-before.jpg and /dev/null differ diff --git a/docs/assets/ui-design-review/hierarchy-after.jpg b/docs/assets/ui-design-review/hierarchy-after.jpg deleted file mode 100644 index c237b12a52..0000000000 Binary files a/docs/assets/ui-design-review/hierarchy-after.jpg and /dev/null differ diff --git a/docs/assets/ui-design-review/hierarchy-before.jpg b/docs/assets/ui-design-review/hierarchy-before.jpg deleted file mode 100644 index 263500aa79..0000000000 Binary files a/docs/assets/ui-design-review/hierarchy-before.jpg and /dev/null differ diff --git a/docs/assets/ui-design-review/icon-optics-after.jpg b/docs/assets/ui-design-review/icon-optics-after.jpg deleted file mode 100644 index 678cee8251..0000000000 Binary files a/docs/assets/ui-design-review/icon-optics-after.jpg and /dev/null differ diff --git a/docs/assets/ui-design-review/icon-optics-before.jpg b/docs/assets/ui-design-review/icon-optics-before.jpg deleted file mode 100644 index 767db03de9..0000000000 Binary files a/docs/assets/ui-design-review/icon-optics-before.jpg and /dev/null differ diff --git a/docs/assets/ui-design-review/states-after.jpg b/docs/assets/ui-design-review/states-after.jpg deleted file mode 100644 index 453b65fd5d..0000000000 Binary files a/docs/assets/ui-design-review/states-after.jpg and /dev/null differ diff --git a/docs/assets/ui-design-review/states-before.jpg b/docs/assets/ui-design-review/states-before.jpg deleted file mode 100644 index 9015fdddf0..0000000000 Binary files a/docs/assets/ui-design-review/states-before.jpg and /dev/null differ diff --git a/docs/cookbook/reviewing-ui-design.i18n.yaml b/docs/cookbook/reviewing-ui-design.i18n.yaml index a0c2df7b7b..e36a105c61 100644 --- a/docs/cookbook/reviewing-ui-design.i18n.yaml +++ b/docs/cookbook/reviewing-ui-design.i18n.yaml @@ -9,20 +9,20 @@ en: d42b121ca63177aa zh: 68b637fae3252c7b /cookbook-review-a-ui-design/summary: - en: bba82e6d46477c21 - zh: 1895633f986845a0 + en: 71c864587a5d4433 + zh: fb58eb9ae3f2ed94 /cookbook-review-a-ui-design/table-of-contents: en: 84af073b2a7eca95 zh: 750633fa3c458d5b /cookbook-review-a-ui-design/1-define-the-page-or-modal-in-scope: - en: bcbda8081f968a50 - zh: 21ab7a92e677d171 + en: c9ee94acd903d809 + zh: c8d07c75ba94531b /cookbook-review-a-ui-design/1-define-the-page-or-modal-in-scope/select-scope-by-visual-impact: en: ef9ad1428375f1d9 zh: 8f59cd04947c16dd /cookbook-review-a-ui-design/2-inspect-the-task-and-its-implementation: - en: 4f0c8520a764ea4d - zh: a0317a8ec85f95a2 + en: 86301e7487e9cd74 + zh: f13bc3da0b2ac2d3 /cookbook-review-a-ui-design/2-inspect-the-task-and-its-implementation/reconcile-the-baseline-across-the-whole-interface: en: 76d008d0bac44f1f zh: 2357d78f350b5540 @@ -33,8 +33,8 @@ en: 61b9e821e98b042a zh: 9b67719f013e7c3c /cookbook-review-a-ui-design/3-preserve-the-starting-point: - en: 1bb17af79c3cfa21 - zh: 95ed56dcde3647f7 + en: a0f8e8d720097515 + zh: 4ff54f0c03bfdb48 /cookbook-review-a-ui-design/4-change-the-smallest-responsible-component: en: 8bcdb909b6825a5e zh: e140ca3873b302b9 @@ -45,8 +45,8 @@ en: cea04ecd81785ca2 zh: b321ae244f050b1c /cookbook-review-a-ui-design/6-deliver-the-complete-evidence/comparison-delivery-and-cumulative-changes: - en: 8f8dd0e9144b614d - zh: c423c08c9706cdfa + en: c81cdec4ac3decca + zh: 9dcb16b292414fda /cookbook-review-a-ui-design/further-exploration: en: 98ac3512211d94ae zh: 055418a72f29a15b diff --git a/docs/cookbook/reviewing-ui-design.md b/docs/cookbook/reviewing-ui-design.md index 0a89bf3d46..9e2cd7f2f9 100644 --- a/docs/cookbook/reviewing-ui-design.md +++ b/docs/cookbook/reviewing-ui-design.md @@ -12,6 +12,8 @@ Use this cookbook for explicitly requested comprehensive reviews and for evidenc Check the complete icon box, including intentional internal whitespace, text columns and gaps before judging the drawn contour. Hit targets are not icon boxes; do not align each glyph’s painted pixels independently. See the [alignment principle](../ui-design-review-cases.md#alignment). +Check associated icons and text against the [same-foreground rule](../../.agents/skills/dsh-ui-icons/SKILL.md#placement-and-use), including submenu values with chevrons and search placeholders with magnifiers. Compare rendered color and opacity in both themes; preserve semantic exceptions. + ## Table of Contents - [1. Define the page or modal in scope](#proposition) @@ -28,7 +30,7 @@ Check the complete icon box, including intentional internal whitespace, text col Identify the user task and affected page or modal. Record scope when several regions, consumers or design choices need coordination; a straightforward local change needs no separate plan. For an explicitly requested comprehensive review, enumerate the requested pages/modals and relevant states. Do not present local inspection as a whole-page result. -Use the [judgment priorities](../ui-design-review-cases.md#judgment) across that scope: alignment and spatial grouping first, then density, hierarchy, states, component choice, icon optics and geometry. Express each finding as an observable relationship, such as content appearing closer to the next group than to its own label. Follow the user’s requested order and authorization; a full review can identify multiple related defects, and existing implementation authorization does not require renewed approval for routine adjustments. +Use the [judgment priorities](../ui-design-review-cases.md#judgment) across that scope: alignment and spatial grouping first, then density, hierarchy, states, component choice, icon optics and geometry. Express each finding as an observable relationship, such as content appearing closer to the next group than to its own label. Follow the user’s requested order and authorization; a full review can identify multiple related defects, and permission to implement routine adjustments does not replace the [required designer/product review](../../.agents/skills/dsh-client-ui-ux/SKILL.md#design-review-escalation). Read the [client UI skill](../../.agents/skills/dsh-client-ui-ux/SKILL.md) and the applicable architecture before editing. Use the [responsive skill](../../.agents/skills/dsh-responsive-ui/SKILL.md) for width and input changes, the [style reference](../web-styling.md) for tokens, and the [radius standard](../ui-radius.md) for corner geometry. This workflow adds review and evidence steps, not another set of visual tokens. @@ -56,6 +58,8 @@ Inspect the affected result at the normal application entry point. Reuse an inst For ordinary changes, a finding needs its location, visible problem, correction and verification. Add source ownership, alternatives and conditions that would invalidate the correction when they affect the decision. Prioritize visible or shared defects; differing source numbers alone do not justify standardization. +When diagnosing spacing, record layout boxes, margins, padding, line boxes and visible glyph edges separately. State whether a close control aligns by its button edge or icon box, and check trigger/menu text insets across their different icon sizes. An annotation of visible whitespace is not a measured CSS margin. + ### Reconcile the baseline across the whole interface Use the [applicable-standards map](../ui-design-review-cases.md#review-baseline) to gather the current radius, material, typography, component, feedback, responsive and artwork rules that apply to this task. Record named exceptions and the relevant existing variants. When a personal or external skill differs, use the repository owner; when implementation differs from the owner, preserve the discrepancy as a finding rather than silently choosing one. @@ -98,7 +102,7 @@ For complex findings, explain the compared objects, intended relationship, suppo Preserve a recoverable starting version and relevant captures when a comparison is requested or needed to assess a broader change or regression risk. Routine local changes do not require an extra source snapshot or before image. When retaining a baseline, include existing uncommitted work rather than assuming `HEAD` represents the visible application, and record the source identity and capture conditions. -When captures are needed, save the baseline images and their conditions in a local evidence directory. +When captures are needed, save images and their conditions in `.ui-review/` at the checkout root or another explicitly selected local directory. The repository ignores `.ui-review/` for generated evidence; review tools can remain installed outside the checkout. Use a scene map for comprehensive reviews or multi-state comparisons that need it; simple changes can be checked directly at the affected position. Include expanded rows, dialogs and relevant loading/disabled states when they affect the claim. A collapsed parent does not cover hidden controls. Use safe fixture data for destructive or unavailable states instead of changing a user's real task just for a screenshot. @@ -145,6 +149,8 @@ For a formal comparison report, use before on the left and after on the right. A Deduplicate cumulative summaries by location: pair the earliest reliable before image with the final implementation, retaining comparable conditions. Keep intermediate rounds only as historical evidence, not separate final results; reverted proposals are not current results. List another session's retained changes separately without claiming them. Disclose missing baselines or uncertain ownership. Record actual checks without adding repeated runs as extra coverage. +For an all-changes summary, trace each claim to the cumulative diff, current owner and retained evidence. Separate net changes from behavior already in the baseline; resolve later user revisions before naming final values. Label older captures as historical when they no longer show the current result, and distinguish source-confirmed behavior from a scene inspected again. Feed reusable decisions back to their rule owner and contrasting cases, not local pixel values or an unsupported whole-product pass. + ## Further Exploration diff --git a/docs/cookbook/reviewing-ui-design.zh.md b/docs/cookbook/reviewing-ui-design.zh.md index 87efa18470..feebd0b575 100644 --- a/docs/cookbook/reviewing-ui-design.zh.md +++ b/docs/cookbook/reviewing-ui-design.zh.md @@ -12,6 +12,8 @@ description: "把 DSH 页面或弹窗作为整体审查，按设计原则说明 对齐审查先核对图标完整空间（含有意保留的内部留白）、文字列和间距，再检查实际轮廓。热区不等于图标框；不逐个拉齐 glyph 的像素边缘。判断顺序见[对齐原则](../ui-design-review-cases.zh.md#alignment)。 +按[同前景色规则](../../.agents/skills/dsh-ui-icons/SKILL.md#placement-and-use)核对关联图标与文字，包括子菜单值与箭头、搜索占位文字与放大镜；检查明暗主题中的实际颜色和透明度，保留语义例外。 + ## 目录 - [1. 确定受审页面或弹窗](#proposition) @@ -28,7 +30,7 @@ description: "把 DSH 页面或弹窗作为整体审查，按设计原则说明 确定用户任务和受影响页面或弹窗。涉及多个区域、使用方或设计取舍时记录范围；明确的局部修改不需要单独写计划。用户明确要求完整审查时，列出指定页面／弹窗及相关状态。不能把局部检查表述成整页结论。 -在这个范围内应用[判断优先级](../ui-design-review-cases.zh.md#judgment)：先检查对齐与空间分组，再审查密度、层级、状态、组件选型、图标光学和几何。每个发现写成可观察的关系，例如内容与隔壁组的距离反而小于与自身标签的距离。遵循用户指定的顺序和授权；完整审查可以发现多个相关问题，已有实施授权不需要为常规调整重复请求批准。 +在这个范围内应用[判断优先级](../ui-design-review-cases.zh.md#judgment)：先检查对齐与空间分组，再审查密度、层级、状态、组件选型、图标光学和几何。每个发现写成可观察的关系，例如内容与隔壁组的距离反而小于与自身标签的距离。遵循用户指定的顺序和授权；完整审查可以发现多个相关问题，常规调整的实施授权不能替代[既有设计／产品审查要求](../../.agents/skills/dsh-client-ui-ux/SKILL.md#design-review-escalation)。 编辑前阅读[客户端 UI Skill](../../.agents/skills/dsh-client-ui-ux/SKILL.md)和适用架构。宽度与输入方式变更使用[响应式 Skill](../../.agents/skills/dsh-responsive-ui/SKILL.md)，令牌规则查阅[样式参考](../web-styling.zh.md)，圆角几何查阅[圆角标准](../ui-radius.zh.md)。本流程补充审查和证据步骤，不另建一套视觉令牌。 @@ -56,6 +58,8 @@ description: "把 DSH 页面或弹窗作为整体审查，按设计原则说明 普通改动说明问题位置、可见现象、修正和验证即可。源码归属、替代方案及改法不适用的条件影响判断时再补充。优先处理可见或共享缺陷；源码数值不同本身不能成为统一数值的理由。 +诊断间距时，分别记录布局框、margin、padding、文字行框和字形可见边缘。明确关闭控件按按钮边缘还是图标框对齐，并核对不同图标尺寸下入口与菜单的文本内缩。可见留白的标注不等于测得了 CSS margin。 + ### 在整个界面内核对适用规范 按[适用规范映射](../ui-design-review-cases.zh.md#review-baseline)收集本任务相关的当前圆角、材质、字体、组件、反馈、响应式和图案规则，记录明确例外与相关已有变体。个人或外部 skill 不同时，以仓库所有方为准；实现与所有方不同时，把差异保留为发现，不能默默任选一方。 @@ -98,7 +102,7 @@ description: "把 DSH 页面或弹窗作为整体审查，按设计原则说明 明确要求对照，或较大改动及回归风险需要对照时，保留可恢复的起始版本与相关截图。普通局部修改不要求额外源码快照或修改前截图。保留基线时需包含已有未提交改动，不能假定 `HEAD` 就是当前可见应用，并记录源码身份与截图条件。 -需要截图时，把基线图及其条件保存在本地证据目录。 +需要截图时，把图像及其条件保存在工作树根目录的 `.ui-review/`，或另行明确选择的本地目录。仓库忽略 `.ui-review/` 中的生成证据；审查工具仍可安装在工作树之外。 完整审查或需要追踪多个状态的对照使用场景映射；简单改动可直接检查受影响位置。展开行、弹窗及相关加载／禁用状态影响结论时应纳入，折叠父组件不能覆盖隐藏控件。破坏性或暂不可达状态使用安全 fixture 数据，不为截图而修改用户的真实任务。 @@ -145,6 +149,8 @@ description: "把 DSH 页面或弹窗作为整体审查，按设计原则说明 累计汇总按位置去重：在条件可比的前提下，将最早可靠的修改前截图与最终实现配对。中间轮次只保留为历史证据，不作为独立最终成果；撤销方案不计入现存成果。另一会话的保留改动单列，不归为本次成果。缺少起点或归属不确定时明确说明。记录实际检查，不将重复执行数量当作新增覆盖。 +汇总全部修改时，将每项结论追溯到累计 diff、当前实现所有方及保留证据。区分净改动与基线已有行为，先消解用户后续修订，再给出最终数值。旧截图不再代表当前结果时标为历史证据，并区分源码核验与重新打开场景检查。将可复用的判断回写规则所有方及正反案例，不把局部像素值或缺乏依据的全产品通过结论变成规范。 + ## 延伸阅读 diff --git a/docs/ui-design-review-cases.i18n.yaml b/docs/ui-design-review-cases.i18n.yaml index 3305e0f427..b992b73c97 100644 --- a/docs/ui-design-review-cases.i18n.yaml +++ b/docs/ui-design-review-cases.i18n.yaml @@ -12,11 +12,11 @@ en: 75120a3fd02294c9 zh: 498343d7b9b30e46 /ui-design-principles-and-review-cases/table-of-contents: - en: 683b785991a7952d - zh: e0a9f88db5cf9c45 + en: c5680dfc600a7495 + zh: c76ec05c69f1e93c /ui-design-principles-and-review-cases/what-a-review-must-judge: - en: e51c9f121c18c998 - zh: 93b35a247216be09 + en: eeff4a5f5e487908 + zh: 51eab38ccd10190b /ui-design-principles-and-review-cases/review-the-entire-page-or-modal-as-one-unit: en: 324c8d9a0ff36ebb zh: 3a4c64e15b59f98f @@ -36,8 +36,8 @@ en: f8b0f72251aa044f zh: a8b05ce5f3da4221 /ui-design-principles-and-review-cases/principle-examples: - en: 1ff7bb879b274363 - zh: 4659578bcdea82a3 + en: 7b8a8bdc5acc11d6 + zh: 96820c11d2e61787 /ui-design-principles-and-review-cases/1-alignment: en: 31d18363696173e9 zh: d2bbca62e7ea0120 @@ -51,14 +51,20 @@ en: 81d165cc1c5c1f7e zh: 4aef022e141ced64 /ui-design-principles-and-review-cases/1-alignment/example-a3-alignment-between-rows-and-compound-controls: - en: 0f387b953c8c3e34 - zh: 5362d3467a65ec59 + en: 9e7fae1a4e649ffd + zh: c3992d7dbedbb247 /ui-design-principles-and-review-cases/1-alignment/example-a4-centering-a-content-group-within-its-container: en: 478771b47daf2cba zh: 0eee64751cff6c94 /ui-design-principles-and-review-cases/1-alignment/example-a5-visible-size-and-center-of-peer-controls: - en: dbbb588cbae149f0 - zh: 1352a6eb01d8340f + en: 376359e2a1de44e9 + zh: 2a0b0e4472efefb7 +/ui-design-principles-and-review-cases/1-alignment/example-a6-text-starts-across-triggers-and-menus: + en: 1afbbce3f4908bf2 + zh: aaf54b32b90a2c82 +/ui-design-principles-and-review-cases/1-alignment/example-a7-choosing-the-close-control-edge: + en: c5e9a409c13637bc + zh: 37c915f187d6e9f7 /ui-design-principles-and-review-cases/2-spatial-grouping: en: f50b8851f4ee2ac3 zh: 63076543756c294e @@ -90,8 +96,8 @@ en: 56ecb557d54c1c2e zh: ede48f8451af4111 /ui-design-principles-and-review-cases/4-information-hierarchy/example-c1-color-emphasis-within-one-information-unit: - en: ae07e8886d00c5bb - zh: 1229ab4ae6394c0b + en: c17aea1873e9a1a6 + zh: dc7a8df8a60e582d /ui-design-principles-and-review-cases/5-control-states: en: d247699132b484a0 zh: b71e25d834ce2633 @@ -105,8 +111,11 @@ en: 21c39c7bbfd87382 zh: e30f9a6593b32265 /ui-design-principles-and-review-cases/7-icon-optics/example-o1-optical-alignment-of-different-icon-types: - en: 3301d847dac58dc9 - zh: 1eba9e56df9a39f2 + en: 3858a85bdf6ee111 + zh: 9c8242a594df069f +/ui-design-principles-and-review-cases/7-icon-optics/example-o2-shared-artwork-at-different-consumer-sizes: + en: 6f29eb80bfe3baf4 + zh: eb3161af01dd752e /ui-design-principles-and-review-cases/8-control-geometry-and-corner-relationships: en: 262cfa8e7dfb969f zh: 4987ad06db795885 diff --git a/docs/ui-design-review-cases.md b/docs/ui-design-review-cases.md index a3283ca03e..227edc9cee 100644 --- a/docs/ui-design-review-cases.md +++ b/docs/ui-design-review-cases.md @@ -13,9 +13,9 @@ Consult the relevant cases when a design relationship is unclear. Ordinary chang ## Table of Contents - [What a review must judge](#judgment) -- [Review the entire page or modal](#whole-interface-review) -- [Applicable DSH standards](#review-baseline) -- [How to use examples](#case-selection) +- [Review the entire page or modal as one unit](#whole-interface-review) +- [Combine the applicable standards first](#review-baseline) +- [Choose cases that expose a design decision](#case-selection) - [Principle examples](#case-index) - [1. Alignment](#alignment) - [2. Spatial grouping](#grouping) @@ -40,8 +40,6 @@ The page or modal provides the reference for composition; the [impact scope](coo The reference diagrams explain relationships; they are not implementation captures or accepted before-and-after results. The examples below explain particular principles and do not establish coverage of the page or modal under review. - - ## Review the entire page or modal as one unit @@ -119,6 +117,8 @@ Use these examples to understand a relationship that is unclear. Apply the same | [A3](#case-preview-toolbar) | Alignment between rows and compound controls | | [A4](#case-empty-center) | Centering a content group within its container | | [A5](#case-composer-controls) | Visible size and center of peer controls | +| [A6](#case-trigger-menu-text) | Text starts across triggers and menus | +| [A7](#case-close-control-edge) | Choosing the close-control edge | | [G1](#case-title-actions) | Separating content from its action group | | [G2](#case-team-sections) | Spacing between complex sections | | [G3](#case-plugin-groups) | Nested groups along the reading order | @@ -126,6 +126,7 @@ Use these examples to understand a relationship that is unclear. Apply the same | [C1](#case-search-color) | Color emphasis within one information unit | | [S1](#case-sidebar-state) | Persistent selection beside temporary hover | | [O1](#case-file-optics) | Optical alignment of different icon types | +| [O2](#case-chevron-consumers) | Shared artwork at different consumer sizes | | [R1](#case-model-radius) | Radii across container and control roles | | [R2](#case-checkbox-radius) | Small selection controls within a form | | [R3](#case-automation-radius) | Justified geometry differences between roles | @@ -176,7 +177,7 @@ The comparison below shows actual preset cards with unequal descriptions. On the **Scene and relationship.** Panel controls sit above file-display controls and an “Open in app” split button. The two rows belong to one preview header, while each row contains operations with different scopes. -**Failure and correction.** Each component may be internally centered while the assembled header has unrelated right insets, heights, and group gaps. Relate the upper icon boxes to the complete lower control, preserving internal icon whitespace rather than aligning extra hit padding or an individual glyph’s painted pixels. Align peer control centers; keep display controls together and separate the external-open action. Treat the split button as one unit. Do not force its arrow onto a column intended for an unrelated panel action. +**Failure and correction.** Each component may be internally centered while the assembled header has unrelated right insets, heights, and group gaps. Relate the upper icon boxes to the complete lower control, preserving internal icon whitespace rather than aligning extra hit padding or an individual glyph’s painted pixels. Align peer control centers; keep display controls together and separate the external-open action. Treat the split button as one unit. Reducing its outer width can equalize visible gaps while retaining the preceding icon columns; verify both segment targets and the frame’s contribution to layout. Do not force its arrow onto a column intended for an unrelated panel action. **Acceptance.** Inspect both rows with the path, tabs, and content edge visible. Repeat with a long path and a narrow pane. A row of standalone icons is not a substitute for the actual split control. @@ -198,6 +199,20 @@ The comparison below shows actual preset cards with unequal descriptions. On the **Acceptance.** Compare both bases and centers in empty, enabled, busy/stop, and narrow layouts. Review the toolbar alongside the composer outline, not as two isolated button screenshots. A reference product's unequal controls do not override an explicit DSH requirement for equal bases. + +### Example A6: Text starts across triggers and menus + +**Scene and relationship.** A permission trigger uses a larger, heavier icon than its menu rows, but their corresponding labels should start on one axis. A search prompt, result heading and option label can share a similar reading edge. + +**Correction and acceptance.** Sum each surface’s border, padding, leading slot and gap before adjusting it. Matching only icon sizes or outer card edges leaves different text starts. Check the assembled open menu, longer labels and narrow layouts; distinguish device-pixel rounding of portal coordinates from a whole inset mismatch. + + +### Example A7: Choosing the close-control edge + +**Scene and relationship.** A modal has a close glyph inside a larger button and a footer action at the content edge. An icon-box edge and a button edge imply different header insets. + +**Correction and acceptance.** Name the intended edge before changing the shared header. If the full button aligns with the footer action, retain the icon’s internal centering instead of pulling it to that edge. An explicitly icon-aligned composition remains a distinct variant. Check short and wrapping titles, description/body combinations and footer actions, and preserve the target size. + ## 2. Spatial grouping @@ -292,7 +307,7 @@ Typography participates in geometry: compare text starts, baselines and line box **Scene and relationship.** Compare the empty automation search with the expanded sidebar search. Both pair a magnifier with a prompt, but one makes the icon darker and the other makes the text darker. -**Correction and acceptance.** Give the empty-field prompt one foreground role, including the leading icon. Compare computed color, opacity, disabled styling, and the background together; two identical color tokens can still differ after an ancestor fades one child. Test empty, typed, focused, disabled, light, and dark variants. Typed query text and an independently actionable clear button need not use the placeholder's weaker role. +**Correction and acceptance.** Give the empty-field prompt one foreground role, including the leading icon. Compare computed color, opacity, disabled styling, and the background together; two identical color tokens can still differ after an ancestor fades one child. Test empty, typed, focused, disabled, light, and dark variants. Typed query text and an independently actionable clear button need not use the placeholder's weaker role. A submenu value and its trailing chevron also form one value: a muted model name with a darker chevron fails that relationship even when their geometry is correct. ## 5. Control states @@ -337,6 +352,13 @@ The [icon skill](../.agents/skills/dsh-ui-icons/SKILL.md) owns interface icon ro **Correction and acceptance.** Preserve the depth indent and common text start. Normalize the placement slots, then compare visible centers and perceived weight within them. Do not move the label to compensate for one glyph, or align all depths to one edge. Inspect at normal size and magnification, with selected backgrounds and long names; the magnified view diagnoses the drawing, while normal size determines whether the result balances. + +### Example O2: Shared artwork at different consumer sizes + +**Scene and relationship.** A chevron appears beside a menu label and inside a larger floating button. Enlarging its drawing within the same view box changes both appearances. + +**Correction and acceptance.** Compare the directional family, both weights and actual consumer sizes. Keep a modest supporting glyph beside text; reduce the floating control’s icon size if needed without shrinking its button. A large glyph sheet alone does not establish balance in either composition. + ## 8. Control geometry and corner relationships diff --git a/docs/ui-design-review-cases.zh.md b/docs/ui-design-review-cases.zh.md index 4167aca0a6..455c18b717 100644 --- a/docs/ui-design-review-cases.zh.md +++ b/docs/ui-design-review-cases.zh.md @@ -14,7 +14,7 @@ description: "DSH 设计判断参考：对齐、空间分组、信息层级、 - [审查究竟要判断什么](#judgment) - [以整页或整个弹窗作为审查单位](#whole-interface-review) -- [适用的 DSH 规范](#review-baseline) +- [先综合适用规范](#review-baseline) - [如何用例子理解原则](#case-selection) - [原则示例索引](#case-index) - [1. 对齐](#alignment) @@ -40,8 +40,6 @@ DSH 的视觉审查优先关注对齐与空间分组。先识别任务和语义 本文原理图解释元素关系，不是实现截图或已验收的修改前后对照。下文例子用于讲清具体原则，不代表已覆盖当前要审查的页面或弹窗。 - - ## 以整页或整个弹窗作为审查单位 @@ -119,6 +117,8 @@ DSH 的视觉审查优先关注对齐与空间分组。先识别任务和语义 | [A3](#case-preview-toolbar) | 多排控件与复合控件的对齐 | | [A4](#case-empty-center) | 内容组相对所属容器居中 | | [A5](#case-composer-controls) | 并列控件的可见尺寸与中心 | +| [A6](#case-trigger-menu-text) | 入口与菜单之间的文本起点 | +| [A7](#case-close-control-edge) | 明确关闭控件的对齐边缘 | | [G1](#case-title-actions) | 内容与操作组的分隔 | | [G2](#case-team-sections) | 复杂分区之间的间距 | | [G3](#case-plugin-groups) | 阅读顺序中的多层分组 | @@ -126,6 +126,7 @@ DSH 的视觉审查优先关注对齐与空间分组。先识别任务和语义 | [C1](#case-search-color) | 同一信息单元的图文强调 | | [S1](#case-sidebar-state) | 持续选中与临时悬停共存 | | [O1](#case-file-optics) | 不同类型图标的光学对齐 | +| [O2](#case-chevron-consumers) | 共享图形在不同使用尺寸下的表现 | | [R1](#case-model-radius) | 不同层级容器与控件的圆角 | | [R2](#case-checkbox-radius) | 表单中小型选择控件的轮廓 | | [R3](#case-automation-radius) | 不同角色之间有依据的几何差异 | @@ -176,7 +177,7 @@ DSH 的视觉审查优先关注对齐与空间分组。先识别任务和语义 **场景与关系。**面板控制位于上排，文件显示控制与“在应用中打开”分段按钮位于下排。两排属于同一个预览页头，每排又包含作用范围不同的操作。 -**错误与修正。**各组件内部可能已经居中，组装后仍出现无关的右边距、高度和分组间距。先按上排图标框与下排完整控件建立尾端关系，保留图标内部留白；不能直接对齐额外热区，也不能追齐单个 glyph 的像素边缘。再对齐并列控件中心，把显示控制收成一组，与外部打开操作分开。分段按钮按完整单元处理，不强迫其箭头与无关的面板操作共用列轴。 +**错误与修正。**各组件内部可能已经居中，组装后仍出现无关的右边距、高度和分组间距。先按上排图标框与下排完整控件建立尾端关系，保留图标内部留白；不能直接对齐额外热区，也不能追齐单个 glyph 的像素边缘。再对齐并列控件中心，把显示控制收成一组，与外部打开操作分开。分段按钮按完整单元处理。缩小其外部宽度可以在保留前方图标列轴的同时，使可见间距相等；应检查两个分段的点击区域，以及边框对布局尺寸的贡献。不强迫其箭头与无关的面板操作共用列轴。 **验收。**保留路径、标签页与内容边缘，一并观察两排；再检查长路径和窄面板。用一排独立图标代替实际分段控件，不能验证这个关系。 @@ -198,6 +199,20 @@ DSH 的视觉审查优先关注对齐与空间分组。先识别任务和语义 **验收。**检查空输入、可发送、忙碌／停止和窄布局中的底板与中心。保留输入框外轮廓一起观察，不能只看两张独立按钮截图。参考产品里不同大小的操作控件，不能覆盖 DSH 已明确的等大底板要求。 + +### 示例 A6：入口与菜单之间的文本起点 + +**场景与关系。**权限入口使用比菜单行更大、更重的图标，但对应文字应从同一轴线开始。搜索提示、结果分组标题和选项文字也可能共享类似的阅读边缘。 + +**修正与验收。**先合计各表面的 border、padding、前导槽和 gap，再调整实现。只统一图标大小或卡片外缘，仍可能留下不同的文字起点。检查组装后的展开菜单、长标签和窄布局；区分浮层坐标按设备像素取整的微差与整段内缩错误。 + + +### 示例 A7：明确关闭控件的对齐边缘 + +**场景与关系。**弹窗的关闭图形位于较大的按钮内，底部操作靠内容边缘。图标框边缘与按钮边缘对应不同的标题栏内缩。 + +**修正与验收。**修改共享标题栏前先明确目标边缘。如果完整按钮与底部操作对齐，就保留图标在按钮内居中，不再把图标拉到该边缘。明确采用图标对齐的构图仍是独立变体。检查短标题、换行标题、说明／正文组合与底部操作，并保留点击区域大小。 + ## 2. 空间分组 @@ -292,7 +307,7 @@ DSH 的视觉审查优先关注对齐与空间分组。先识别任务和语义 **场景与关系。**比较空的自动化搜索框与展开的侧栏搜索框。二者都是放大镜配合提示文字，但一处图标更深，另一处文字更深。 -**修正与验收。**为空输入提示指定一个前景色角色，包含前导图标。联合检查计算后的颜色、透明度、禁用样式与背景；祖先单独淡化某个子元素时，相同 token 仍可能产生不同结果。检查空值、输入文字、焦点、禁用及明暗主题。已输入的查询文字和具有独立操作的清除按钮，不必使用较弱的占位提示色。 +**修正与验收。**为空输入提示指定一个前景色角色，包含前导图标。联合检查计算后的颜色、透明度、禁用样式与背景；祖先单独淡化某个子元素时，相同 token 仍可能产生不同结果。检查空值、输入文字、焦点、禁用及明暗主题。已输入的查询文字和具有独立操作的清除按钮，不必使用较弱的占位提示色。子菜单的值与尾部 chevron 也构成同一个值；即使几何正确，弱化的模型名称配更深的箭头仍不符合该关系。 ## 5. 控件状态 @@ -337,6 +352,13 @@ DSH 的视觉审查优先关注对齐与空间分组。先识别任务和语义 **修正与验收。**保留层级缩进和共同文字起点，先统一放置槽，再比较槽内可见中心与视觉重量。不能移动文字去补偿单个 glyph，也不能把所有深度压到同一边缘。检查正常尺寸和放大图，包含选中底色与长文件名；放大图用于诊断绘制，正常尺寸决定结果是否平衡。 + +### 示例 O2：共享图形在不同使用尺寸下的表现 + +**场景与关系。**同一个 chevron 既出现在菜单文字旁，也出现在较大的悬浮按钮中。在同一 viewBox 内放大绘制范围，会同时改变两处表现。 + +**修正与验收。**对比各方向、两种字重及实际使用尺寸。文字旁保留适度的辅助图形；必要时缩小悬浮控件里的图标，但不缩小按钮。只看放大的图标总表，不能证明这两种构图都平衡。 + ## 8. 控件几何与圆角关系 diff --git a/packages/client/ui-primitives/README.i18n.yaml b/packages/client/ui-primitives/README.i18n.yaml index a9b6afd322..2ff914e59f 100644 --- a/packages/client/ui-primitives/README.i18n.yaml +++ b/packages/client/ui-primitives/README.i18n.yaml @@ -21,8 +21,8 @@ en: eeff2dabd2f7dcb1 zh: a5054d09940b40e8 /deepseek-ai-dsh-client-ui-primitives/use-this-package/controls-and-icons: - en: 8aa561d0c21f177f - zh: 8c1924a20f78f3ff + en: a5580871b06143b6 + zh: 152465da61068c5d /deepseek-ai-dsh-client-ui-primitives/use-this-package/rendering-agent-output: en: e2649937f077d4e0 zh: 6ad604cb5adfc16b diff --git a/packages/client/ui-primitives/README.md b/packages/client/ui-primitives/README.md index 896e5aac0d..a5609e81dd 100644 --- a/packages/client/ui-primitives/README.md +++ b/packages/client/ui-primitives/README.md @@ -96,7 +96,7 @@ Writing your own component in your own package is fine when the need is genuinel ### Controls and icons -The catalog above lists what each export is for; this section covers the behavior that props alone do not show. Product icon names omit artboard sizes and end in `Regular` for the supplied one-pixel artwork or `Medium` for the same geometry at a 1.3px stroke; the `size` prop controls rendered dimensions. Named components keep the chosen weight visible at import sites; the library owns stroke geometry instead of consumer CSS overrides. Each product icon renders an `` box with one `` of its `dsw-icon--` symbol, for example `dsw-icon-search-outline-regular`, and names that id in `data-icon`. `ICON_SYMBOLS` holds every symbol's default SVG document; ui-theme renders the document icon sprite from it, and an icon whose symbol is missing renders nothing. Artwork reached through `` inherits `currentColor` and CSS variables from the use site. Each product, reference, link, and permission glyph intentionally keeps both weight exports even when the current product uses only one, so callers can choose emphasis without adding another API later; fill-only pairs render identically. `IconWarningOutlineRegular`/`Medium` use a circle; `IconWarningTriangleOutlineRegular`/`Medium` use a rounded triangle. `FishLogo` and `BrandWordmark` fill brand slots. `FileTypeIcon` renders the traditional 28px spreadsheet, folder, HTML, image, Markdown, generic, PDF, PPT, video, and Word glyphs, and uses the imported square technology artwork for the established 48 code and configuration categories. The import replaces artwork only: archive-only categories do not extend `CodeFileType`. `classifyFileType` applies exact filename, prefix, suffix, optional project-context, and extension rules in that order; React names win over TypeScript/JavaScript, Angular suffixes win over their base extension, and a Dart file becomes Flutter only when the supplied project files contain a `pubspec.yaml` with `flutter:`. Markdown and SVG remain traditional Markdown and image files. Spreadsheet mappings include CSV, TSV, Excel workbooks and templates, OpenDocument spreadsheets, and Numbers; KEY maps to slides, while RTF/ODT/Pages map to documents. `fileExtension` exposes the same basename and final-dot parsing for adjacent metadata labels. Traditional glyphs use a solid category-colored sheet with a white mark and translucent white corner; the generic code glyph uses angle brackets and a slash at the supplied 1.35px stroke; the generic file uses a grey sheet and darker grey corner. Callers may override the sheet color through `--dsh-file-type-icon-color`. The full-color technology artwork is the deliberate exception and retains its embedded palette. All glyphs are decorative and carry no label. `LinkIconMedium` is the leading glyph for clickable artifact links — globe, folder, code, image, document, or plain paper, and for a `url` link the mark of a well-known site named by its `href` — the developer sites a transcript usually cites (GitHub, GitLab, npm, PyPI, Stack Overflow, MDN, Wikipedia, Hacker News, YouTube, X, Bilibili, Zhihu, Juejin, CSDN) and mainstream search, video, social, shopping, and reference sites (Google, Baidu, DuckDuckGo, TikTok, Netflix, Spotify, Facebook, Instagram, Reddit, Telegram, WhatsApp, WeChat, QQ, Weibo, Taobao, AliExpress, eBay, Quora, V2EX, Apple) — while `classifyLinkPath` folds the shared file types into that existing six-category vocabulary. `ConnectionIndicator` renders a warning-colored disconnected action whose permanent retry glyph marks the retry action beside the owner-supplied outage label, the shared ongoing loader in the same warning color as its label whose one-to-three dots advance every 500ms independently of retry timing, or a success-colored recovered status. Clicking either warning state requests an immediate reconnect; no hover interaction changes the copy. The pill fades in on appearance, fades out for 150ms before unmounting, and sizes to its current label. Its owner supplies visibility, the recovery hold, localized labels, and the immediate-reconnect callback; the primitive uses no native title tooltip. `useAnchoredMaxHeight` keeps bottom-anchored overlays within the visible viewport; an oversized panel keeps the near margin instead of sliding off that edge. A submenu-free portalled `Menu` caps its card height against the layout viewport, with its pinned footer outside the inner scrolling region. `HoverCard` adds 20px to the frame's published top clearance, or keeps 20px in native fullscreen, while preserving its own minimum margin in ordinary browsers; while an anchor is inside that top strip, the card is never pushed lower than the anchor's bottom edge plus its gap. `HoverCard` keeps its portaled preview reachable across the anchor gap and can expose a copy button through the `copyText` prop. Touch entry does not open its preview or intercept the anchor action. Mouse entry requires an available hover-capable pointer; keyboard focus remains independent of that capability. Its `preview` variant uses the anchor or `widthAnchorRef` element’s width minus 48px, centers the panel with 24px side insets, and places it above or below the row within the viewport. The panel keeps the frame’s top clearance except below an anchor inside the top strip, caps its height at 420px, and follows content and anchor resizing; Escape or pointer and keyboard activation of the anchor dismisses it. The whole preview fades in and out over 100ms; a closing preview stops receiving pointer input and unmounts after the fade. Re-entering the anchor during the fade restores it. Reduced-motion preferences suppress the transition. Copy labels are required only when copying is enabled. `HoverCard` and nested action tooltips display independently; use `Tooltip.portal` to layer the small bubble above the card. A visible nested `Tooltip` suppresses only its enclosing tooltip, not the hover card. `Toast` uses the owner's `holdMs` for both the fade delay and its hold-and-fade lifetime. Rerenders with unchanged `holdMs` do not restart that lifetime; completion uses the latest callback, and fully faded actions cannot receive input. A new component key restarts the banner. `rankByName` is the `/` menu's shared candidate ranker for the command and skill sources: the query must be a case-insensitive ordered subsequence of the name; prefix hits rank first, then alignment score, then source order. Portalled `Menu` lists use CSS Anchor Positioning to follow their trigger and constrain their dimensions to the layout viewport. Every placement candidate reserves 12px layout-viewport margins and uses the frame overlay inset as its minimum top edge; pointer-positioned contextual menus keep 12px at the top. When the preferred placement cannot fit, CSS tries a horizontal adjustment or the opposite side before using a window-bounded fallback. Browser zoom and panning move the menu with the page; it may extend beyond the visual viewport, including while the keyboard is open. Internal scrolling, dismissal, and focus restoration remain independent. `Menu.autoFocus` focuses its first enabled item, supports Arrow Up/Down and Home/End navigation, and focuses the first button in the anchor on Escape; it is opt-in for action menus. +The catalog above lists what each export is for; this section covers the behavior that props alone do not show. Product icon names omit artboard sizes and end in `Regular` or `Medium`. Line artwork uses stroke widths of 1 and 1.3 SVG user units respectively; the `size` prop controls rendered dimensions. Strokes scale with the viewport: a 1-unit stroke in a 16-unit view box renders at 0.875 CSS px at 14px and 0.75 CSS px at 12px, before further transforms. The renderer does not apply non-scaling strokes; filled contours scale as geometry and do not respond to stroke-width changes. Shared menus render icons at 14px, or 12px in compact lists, through `Menu.module.css`; these are rendered sizes, not fixed stroke widths. Named components keep the chosen weight visible at import sites; the library owns stroke geometry instead of consumer CSS overrides. Each product icon renders an `` box with one `` of its `dsw-icon--` symbol, for example `dsw-icon-search-outline-regular`, and names that id in `data-icon`. `ICON_SYMBOLS` holds every symbol's default SVG document; ui-theme renders the document icon sprite from it, and an icon whose symbol is missing renders nothing. Artwork reached through `` inherits `currentColor` and CSS variables from the use site. Each product, reference, link, and permission glyph intentionally keeps both weight exports even when the current product uses only one, so callers can choose emphasis without adding another API later; fill-only pairs render identically. `IconWarningOutlineRegular`/`Medium` use a circle; `IconWarningTriangleOutlineRegular`/`Medium` use a rounded triangle. `FishLogo` and `BrandWordmark` fill brand slots. `FileTypeIcon` renders the traditional 28px spreadsheet, folder, HTML, image, Markdown, generic, PDF, PPT, video, and Word glyphs, and uses the imported square technology artwork for the established 48 code and configuration categories. The import replaces artwork only: archive-only categories do not extend `CodeFileType`. `classifyFileType` applies exact filename, prefix, suffix, optional project-context, and extension rules in that order; React names win over TypeScript/JavaScript, Angular suffixes win over their base extension, and a Dart file becomes Flutter only when the supplied project files contain a `pubspec.yaml` with `flutter:`. Markdown and SVG remain traditional Markdown and image files. Spreadsheet mappings include CSV, TSV, Excel workbooks and templates, OpenDocument spreadsheets, and Numbers; KEY maps to slides, while RTF/ODT/Pages map to documents. `fileExtension` exposes the same basename and final-dot parsing for adjacent metadata labels. Traditional glyphs use a solid category-colored sheet with a white mark and translucent white corner; the generic code glyph uses angle brackets and a slash at the supplied 1.35px stroke; the generic file uses a grey sheet and darker grey corner. Callers may override the sheet color through `--dsh-file-type-icon-color`. The full-color technology artwork is the deliberate exception and retains its embedded palette. All glyphs are decorative and carry no label. `LinkIconMedium` is the leading glyph for clickable artifact links — globe, folder, code, image, document, or plain paper, and for a `url` link the mark of a well-known site named by its `href` — the developer sites a transcript usually cites (GitHub, GitLab, npm, PyPI, Stack Overflow, MDN, Wikipedia, Hacker News, YouTube, X, Bilibili, Zhihu, Juejin, CSDN) and mainstream search, video, social, shopping, and reference sites (Google, Baidu, DuckDuckGo, TikTok, Netflix, Spotify, Facebook, Instagram, Reddit, Telegram, WhatsApp, WeChat, QQ, Weibo, Taobao, AliExpress, eBay, Quora, V2EX, Apple) — while `classifyLinkPath` folds the shared file types into that existing six-category vocabulary. `ConnectionIndicator` renders a warning-colored disconnected action whose permanent retry glyph marks the retry action beside the owner-supplied outage label, the shared ongoing loader in the same warning color as its label whose one-to-three dots advance every 500ms independently of retry timing, or a success-colored recovered status. Clicking either warning state requests an immediate reconnect; no hover interaction changes the copy. The pill fades in on appearance, fades out for 150ms before unmounting, and sizes to its current label. Its owner supplies visibility, the recovery hold, localized labels, and the immediate-reconnect callback; the primitive uses no native title tooltip. `useAnchoredMaxHeight` keeps bottom-anchored overlays within the visible viewport; an oversized panel keeps the near margin instead of sliding off that edge. A submenu-free portalled `Menu` caps its card height against the layout viewport, with its pinned footer outside the inner scrolling region. `HoverCard` adds 20px to the frame's published top clearance, or keeps 20px in native fullscreen, while preserving its own minimum margin in ordinary browsers; while an anchor is inside that top strip, the card is never pushed lower than the anchor's bottom edge plus its gap. `HoverCard` keeps its portaled preview reachable across the anchor gap and can expose a copy button through the `copyText` prop. Touch entry does not open its preview or intercept the anchor action. Mouse entry requires an available hover-capable pointer; keyboard focus remains independent of that capability. Its `preview` variant uses the anchor or `widthAnchorRef` element’s width minus 48px, centers the panel with 24px side insets, and places it above or below the row within the viewport. The panel keeps the frame’s top clearance except below an anchor inside the top strip, caps its height at 420px, and follows content and anchor resizing; Escape or pointer and keyboard activation of the anchor dismisses it. The whole preview fades in and out over 100ms; a closing preview stops receiving pointer input and unmounts after the fade. Re-entering the anchor during the fade restores it. Reduced-motion preferences suppress the transition. Copy labels are required only when copying is enabled. `HoverCard` and nested action tooltips display independently; use `Tooltip.portal` to layer the small bubble above the card. A visible nested `Tooltip` suppresses only its enclosing tooltip, not the hover card. `Toast` uses the owner's `holdMs` for both the fade delay and its hold-and-fade lifetime. Rerenders with unchanged `holdMs` do not restart that lifetime; completion uses the latest callback, and fully faded actions cannot receive input. A new component key restarts the banner. `rankByName` is the `/` menu's shared candidate ranker for the command and skill sources: the query must be a case-insensitive ordered subsequence of the name; prefix hits rank first, then alignment score, then source order. Portalled `Menu` lists use CSS Anchor Positioning to follow their trigger and constrain their dimensions to the layout viewport. Every placement candidate reserves 12px layout-viewport margins and uses the frame overlay inset as its minimum top edge; pointer-positioned contextual menus keep 12px at the top. When the preferred placement cannot fit, CSS tries a horizontal adjustment or the opposite side before using a window-bounded fallback. Browser zoom and panning move the menu with the page; it may extend beyond the visual viewport, including while the keyboard is open. Internal scrolling, dismissal, and focus restoration remain independent. `Menu.autoFocus` focuses its first enabled item, supports Arrow Up/Down and Home/End navigation, and focuses the first button in the anchor on Escape; it is opt-in for action menus. `Tooltip` reads the anchor on hover or keyboard focus and fits its bubble from `ResizeObserver` border-box sizes. It stays hidden until its first fit, prefers the requested side, then tries the opposite and perpendicular sides, sliding along the anchor without covering it when a side fits. Horizontal placements keep a 10px gap; vertical placements use `gap` (8px by default). Width and height stay within a 12px viewport margin; text wraps, and content taller than the viewport scrolls when pinned. If no side fits, a stable viewport-bounded fallback can overlap the anchor. Viewport resize refreshes the anchor coordinates; label-size changes reuse them. Fitting does not synchronously measure the bubble or trigger a React render. Touch presses dismiss unpinned hints and do not trigger hover hints, including compatibility mouse events. Mouse entry opens hints only while `(any-hover: hover)` reports an available hover-capable input, excluding iOS mouse entry caused by a tapped icon changing. Keyboard focus and explicit click-to-open explanations remain available on touch-only devices. Opt-in `openOnClick` lets an informational button pin the bubble by click or tap and associates it with the anchor description. Another click or tap, Escape, Tab, or an outside pointerdown closes it. Ordinary action buttons execute their action directly without a touch tooltip. Opt-in `onlyWhenClipped` shows the bubble only when the anchor or an HTML element inside it overflows horizontally when the bubble is about to show, so a label that repeats ellipsis-cut text appears only while it adds information. diff --git a/packages/client/ui-primitives/README.zh.md b/packages/client/ui-primitives/README.zh.md index b1dcfc2e99..ebbad8cd83 100644 --- a/packages/client/ui-primitives/README.zh.md +++ b/packages/client/ui-primitives/README.zh.md @@ -96,7 +96,7 @@ kind: "package-library" ### 控件与图标 -上面的目录说明每个导出的用途；本节讲 props 本身看不出来的行为。产品图标名称不含画板尺寸，以 `Regular` 表示原始 1px 图形，以 `Medium` 表示同一几何的 1.3px 描边；`size` prop 控制渲染尺寸。具名组件让所选线重在导入处可见；描边几何由组件库拥有，而不是由消费方 CSS 覆盖。每个产品图标渲染一个 `` 框，其中包含一个引用对应 `dsw-icon--` symbol 的 ``，例如 `dsw-icon-search-outline-regular`，并在 `data-icon` 中写出该 id。`ICON_SYMBOLS` 保存每个 symbol 的默认 SVG 文档；ui-theme 据此渲染文档的图标 sprite，缺少对应 symbol 的图标不渲染任何内容。通过 `` 引用的图形会从使用处继承 `currentColor` 与 CSS 变量。每个产品、引用、链接与权限图形都会有意保留两种线重导出，即使当前产品只使用其中一种，也让调用方无需再次扩展 API 就能选择强调程度；仅填充的成对图形外观相同。`IconWarningOutlineRegular`/`Medium` 使用圆形；`IconWarningTriangleOutlineRegular`/`Medium` 使用圆角三角形。`FishLogo` 与 `BrandWordmark` 填充品牌 slot。`FileTypeIcon` 渲染传统的 28px spreadsheet、folder、HTML、image、Markdown、generic、PDF、PPT、video 与 Word 图形，并为现有 48 个代码和配置类别使用导入的方形技术图形。该导入只替换图形：资源包中额外的类别不会扩展 `CodeFileType`。`classifyFileType` 按完整文件名、前缀、后缀、可选项目上下文、扩展名的顺序匹配；React 文件名优先于 TypeScript/JavaScript，Angular 后缀优先于基础扩展名，只有传入的项目文件包含带 `flutter:` 的 `pubspec.yaml` 时 Dart 文件才使用 Flutter。Markdown 与 SVG 仍分别使用传统 Markdown 与图片图形。表格映射包括 CSV、TSV、Excel 工作簿与模板、OpenDocument 表格和 Numbers；KEY 映射为幻灯片，RTF/ODT/Pages 映射为文档。`fileExtension` 为相邻元数据 label 暴露同一套 basename 与最终点号解析。传统图形使用实色分类底板、白色标记和半透明白色折角；通用代码图形使用尖括号与斜线，保留原图 1.35px 描边；通用文件使用灰色底板与较深灰色折角。调用方可通过 `--dsh-file-type-icon-color` 覆盖底板颜色。全彩技术图形是明确例外，会保留其内嵌调色板。所有图形都是装饰性的，不自带 label。`LinkIconMedium` 是可点击产物链接的前置图形——地球、文件夹、代码、图片、文档或纸张，`url` 链接的 `href` 指向已知站点时则改用该站点自己的标记——转写内容常引用的开发者站点（GitHub、GitLab、npm、PyPI、Stack Overflow、MDN、Wikipedia、Hacker News、YouTube、X、Bilibili、知乎、掘金、CSDN），以及主流搜索、视频、社交、购物与参考资料站点（Google、百度、DuckDuckGo、TikTok、Netflix、Spotify、Facebook、Instagram、Reddit、Telegram、WhatsApp、微信、QQ、微博、淘宝、速卖通、eBay、Quora、V2EX、Apple）——`classifyLinkPath` 把共享文件类型折叠进原有六类词汇。`ConnectionIndicator` 可渲染警告色的断联操作（常驻重试图形指明重试动作，断联文案由持有方提供）、与文案使用相同警告色的共享 ongoing loading 加一至三个点以独立于 retry 时序的 500ms 节奏推进的连接中状态，或成功色的恢复状态。点击任一警告状态都会请求立即重连；没有任何悬停交互会改变文案。药丸出现时淡入、卸载前淡出 150ms，宽度随当前 label 自适应。它的持有方提供可见性、恢复驻留时间、本地化 label 与立即重连回调；该原语不使用原生 title tooltip。`useAnchoredMaxHeight` 将底部锚定浮层限制在可见视口内；过大的面板保留近端边距，不会滑出该边缘。无子菜单的 portal 模式 `Menu` 按布局视口限制卡片高度，固定页脚位于内部滚动区域之外。`HoverCard` 在框架发布的顶部占用量上增加 20px，原生全屏时保留 20px，普通浏览器中沿用自身的最小边距；锚点位于该顶部区域内时，卡片不会被推到低于锚点底边加自身间距的位置。`HoverCard` 通过指针离开宽限期让采用 portal 的预览在跨过锚点间隙时仍可触及，并可通过 `copyText` prop 提供复制按钮。触摸进入不会打开预览，也不会拦截锚点操作。鼠标进入要求存在可悬停的指针设备；键盘聚焦不依赖该能力。其 `preview` 变体使用 anchor 或 `widthAnchorRef` 元素的宽度减去 48px，左右各内缩 24px，并在视口内放置于行的上方或下方。浮层避开框架顶部保留区（位于顶部区域内的锚点下方时除外），高度最多 420px，会跟随内容及 anchor 尺寸变化；Escape 或通过鼠标和键盘激活锚点可将其关闭。整个浮层的淡入和淡出各持续 100ms；关闭中的浮层停止接收指针输入，淡出后卸载。在淡出期间移回锚点可恢复显示。减少动态效果偏好会禁用过渡动画。只有启用复制时才必须提供复制标签。`HoverCard` 与嵌套的操作提示独立显示；使用 `Tooltip.portal` 将小气泡置于卡片上层。可见的嵌套 `Tooltip` 只隐藏外层 tooltip，不隐藏悬停卡片。`Toast` 使用调用方的 `holdMs` 同时控制淡出延迟与停留加淡出的总时长。`holdMs` 未变时，父组件重渲染不会重启该生命周期；完成时调用最新回调，完全淡出的操作不能接收输入。新的组件 key 会重新开始横幅周期。`rankByName` 是 `/` 菜单命令源与 skill（技能）源共享的候选排序器：查询必须是名字的不区分大小写的有序子序列；前缀命中排最前，其次按对齐分数，再按来源顺序。 portal 模式的 `Menu` 通过 CSS Anchor Positioning 跟随触发元素，并按布局视口限制尺寸。每个候选位置都保留 12px 布局视口边距，并将框架浮层起点作为顶部下限；按指针定位的上下文菜单顶部保留 12px。首选位置放不下时，CSS 尝试横向调整或相反方向，最后使用窗口内的回退位置。浏览器缩放和平移时，菜单随页面移动，可以超出视觉视口，包括键盘打开时。内部滚动、菜单关闭和焦点恢复保持独立。`Menu.autoFocus` 聚焦首个启用项，支持上下方向键与 Home/End 导航，并在 Escape 时聚焦 anchor 内的第一个按钮；操作菜单可显式启用。 +上面的目录说明每个导出的用途；本节讲 props 本身看不出来的行为。产品图标名称不含画板尺寸，以 `Regular` 或 `Medium` 结尾。线条图形分别使用 1 和 1.3 SVG 用户单位的描边宽度；`size` prop 控制渲染尺寸。描边随视口缩放：16 单位 viewBox 中宽度为 1 的描边，在 14px 下为 0.875 CSS px，在 12px 下为 0.75 CSS px，尚未计入额外变换。渲染器不使用非缩放描边；填充轮廓随几何缩放，不受 stroke-width 变化影响。共享菜单通过 `Menu.module.css` 将图标渲染为 14px，紧凑列表为 12px；这些是渲染尺寸，不是固定描边宽度。具名组件让所选线重在导入处可见；描边几何由组件库拥有，而不是由消费方 CSS 覆盖。每个产品图标渲染一个 `` 框，其中包含一个引用对应 `dsw-icon--` symbol 的 ``，例如 `dsw-icon-search-outline-regular`，并在 `data-icon` 中写出该 id。`ICON_SYMBOLS` 保存每个 symbol 的默认 SVG 文档；ui-theme 据此渲染文档的图标 sprite，缺少对应 symbol 的图标不渲染任何内容。通过 `` 引用的图形会从使用处继承 `currentColor` 与 CSS 变量。每个产品、引用、链接与权限图形都会有意保留两种线重导出，即使当前产品只使用其中一种，也让调用方无需再次扩展 API 就能选择强调程度；仅填充的成对图形外观相同。`IconWarningOutlineRegular`/`Medium` 使用圆形；`IconWarningTriangleOutlineRegular`/`Medium` 使用圆角三角形。`FishLogo` 与 `BrandWordmark` 填充品牌 slot。`FileTypeIcon` 渲染传统的 28px spreadsheet、folder、HTML、image、Markdown、generic、PDF、PPT、video 与 Word 图形，并为现有 48 个代码和配置类别使用导入的方形技术图形。该导入只替换图形：资源包中额外的类别不会扩展 `CodeFileType`。`classifyFileType` 按完整文件名、前缀、后缀、可选项目上下文、扩展名的顺序匹配；React 文件名优先于 TypeScript/JavaScript，Angular 后缀优先于基础扩展名，只有传入的项目文件包含带 `flutter:` 的 `pubspec.yaml` 时 Dart 文件才使用 Flutter。Markdown 与 SVG 仍分别使用传统 Markdown 与图片图形。表格映射包括 CSV、TSV、Excel 工作簿与模板、OpenDocument 表格和 Numbers；KEY 映射为幻灯片，RTF/ODT/Pages 映射为文档。`fileExtension` 为相邻元数据 label 暴露同一套 basename 与最终点号解析。传统图形使用实色分类底板、白色标记和半透明白色折角；通用代码图形使用尖括号与斜线，保留原图 1.35px 描边；通用文件使用灰色底板与较深灰色折角。调用方可通过 `--dsh-file-type-icon-color` 覆盖底板颜色。全彩技术图形是明确例外，会保留其内嵌调色板。所有图形都是装饰性的，不自带 label。`LinkIconMedium` 是可点击产物链接的前置图形——地球、文件夹、代码、图片、文档或纸张，`url` 链接的 `href` 指向已知站点时则改用该站点自己的标记——转写内容常引用的开发者站点（GitHub、GitLab、npm、PyPI、Stack Overflow、MDN、Wikipedia、Hacker News、YouTube、X、Bilibili、知乎、掘金、CSDN），以及主流搜索、视频、社交、购物与参考资料站点（Google、百度、DuckDuckGo、TikTok、Netflix、Spotify、Facebook、Instagram、Reddit、Telegram、WhatsApp、微信、QQ、微博、淘宝、速卖通、eBay、Quora、V2EX、Apple）——`classifyLinkPath` 把共享文件类型折叠进原有六类词汇。`ConnectionIndicator` 可渲染警告色的断联操作（常驻重试图形指明重试动作，断联文案由持有方提供）、与文案使用相同警告色的共享 ongoing loading 加一至三个点以独立于 retry 时序的 500ms 节奏推进的连接中状态，或成功色的恢复状态。点击任一警告状态都会请求立即重连；没有任何悬停交互会改变文案。药丸出现时淡入、卸载前淡出 150ms，宽度随当前 label 自适应。它的持有方提供可见性、恢复驻留时间、本地化 label 与立即重连回调；该原语不使用原生 title tooltip。`useAnchoredMaxHeight` 将底部锚定浮层限制在可见视口内；过大的面板保留近端边距，不会滑出该边缘。无子菜单的 portal 模式 `Menu` 按布局视口限制卡片高度，固定页脚位于内部滚动区域之外。`HoverCard` 在框架发布的顶部占用量上增加 20px，原生全屏时保留 20px，普通浏览器中沿用自身的最小边距；锚点位于该顶部区域内时，卡片不会被推到低于锚点底边加自身间距的位置。`HoverCard` 通过指针离开宽限期让采用 portal 的预览在跨过锚点间隙时仍可触及，并可通过 `copyText` prop 提供复制按钮。触摸进入不会打开预览，也不会拦截锚点操作。鼠标进入要求存在可悬停的指针设备；键盘聚焦不依赖该能力。其 `preview` 变体使用 anchor 或 `widthAnchorRef` 元素的宽度减去 48px，左右各内缩 24px，并在视口内放置于行的上方或下方。浮层避开框架顶部保留区（位于顶部区域内的锚点下方时除外），高度最多 420px，会跟随内容及 anchor 尺寸变化；Escape 或通过鼠标和键盘激活锚点可将其关闭。整个浮层的淡入和淡出各持续 100ms；关闭中的浮层停止接收指针输入，淡出后卸载。在淡出期间移回锚点可恢复显示。减少动态效果偏好会禁用过渡动画。只有启用复制时才必须提供复制标签。`HoverCard` 与嵌套的操作提示独立显示；使用 `Tooltip.portal` 将小气泡置于卡片上层。可见的嵌套 `Tooltip` 只隐藏外层 tooltip，不隐藏悬停卡片。`Toast` 使用调用方的 `holdMs` 同时控制淡出延迟与停留加淡出的总时长。`holdMs` 未变时，父组件重渲染不会重启该生命周期；完成时调用最新回调，完全淡出的操作不能接收输入。新的组件 key 会重新开始横幅周期。`rankByName` 是 `/` 菜单命令源与 skill（技能）源共享的候选排序器：查询必须是名字的不区分大小写的有序子序列；前缀命中排最前，其次按对齐分数，再按来源顺序。 portal 模式的 `Menu` 通过 CSS Anchor Positioning 跟随触发元素，并按布局视口限制尺寸。每个候选位置都保留 12px 布局视口边距，并将框架浮层起点作为顶部下限；按指针定位的上下文菜单顶部保留 12px。首选位置放不下时，CSS 尝试横向调整或相反方向，最后使用窗口内的回退位置。浏览器缩放和平移时，菜单随页面移动，可以超出视觉视口，包括键盘打开时。内部滚动、菜单关闭和焦点恢复保持独立。`Menu.autoFocus` 聚焦首个启用项，支持上下方向键与 Home/End 导航，并在 Escape 时聚焦 anchor 内的第一个按钮；操作菜单可显式启用。 `Tooltip` 在悬停或键盘聚焦时读取锚点位置，再根据 `ResizeObserver` 提供的边框盒尺寸调整气泡。首次定位前保持隐藏，优先使用指定方向，再尝试相反方向和垂直于该方向的两侧；只要某一侧容得下，就沿锚点平移而不遮挡锚点。左右放置保留 10px 间距，上下放置使用 `gap`（默认 8px）。宽高限制在视口内并保留 12px 边距；文本自动换行，超出视口高度的内容在固定气泡后可滚动。若所有方向都放不下，则使用稳定的视口内回退位置，可能遮挡锚点。视口尺寸变化会重新读取锚点坐标，标签尺寸变化则复用坐标；定位不会同步测量气泡，也不会触发 React 渲染。 触摸按下会关闭未固定的提示，且不会触发悬停提示，包括触摸后的兼容鼠标事件。只有 `(any-hover: hover)` 表明存在可悬停的输入设备时，鼠标进入才会打开提示，从而排除 iOS 因已点击图标变化而生成的鼠标进入事件。仅有触摸输入的设备仍可使用键盘聚焦提示和显式点击打开的说明。信息按钮可显式启用 `openOnClick`，通过鼠标或触摸点击固定气泡供阅读，并将内容关联为锚点的无障碍描述；再次点击、Escape、Tab 或外部 pointerdown 会关闭。普通操作按钮在触摸点击时直接执行操作，不显示 Tooltip。可选的 `onlyWhenClipped` 只在气泡即将显示时锚点或其内部某个 HTML 元素横向溢出才显示气泡，因此重复被省略号截断文本的标签只在能补充信息时出现。