docs: define UI design decisions and review workflow

2026-11-09 20:07:43 +08:00 · 2026-11-03 20:38:25 +08:00
parent 54cb44c006
commit cb6834f011
44 changed files with 1635 additions and 58 deletions
@@ -1,77 +1,56 @@
 ---
 name: dsh-client-ui-ux
-description: Design and review DeepSeek Harness client UI changes — visual token discipline, reuse-before-adding, feedback surfaces (toast vs in-place notice vs empty state), overlay and menu safety, platform window adaptation, loading states, and error copy placement. Use when adding or changing product-user-visible GUI behavior in packages/client, or when reviewing such a PR.
+description: Use before implementing any DSH user-visible UI change and during UI review, including layout, copy, icons, styling and interaction states in client, experimental and app packages. Select applicable rules before coding and verify the affected rendered relationships before handoff.
 ---
-# DeepSeek Harness Client UI/UX
+# DeepSeek Harness UI development
-This skill is guidance, not a complete checklist. It covers judgment calls that lint, typecheck, and the i18n gate cannot make: where feedback appears, what gets reused, and how surfaces behave at window edges and across platforms. Copy quality itself follows [dsh-prose-standard](../dsh-prose-standard/SKILL.md); locale ownership follows the [locale-owned copy decision](../../notes/implemented/architecture/2026-08-23-locale-owned-client-ui-copy.md); styling ownership and token rules live in [docs/web-styling.md](../../../docs/web-styling.md) and the [ui-primitives component catalog](../../../packages/client/ui-primitives/README.md#component-catalog) — this skill adds judgment on top of those rules, not a second copy of them.
+Use this entry before changing UI. It owns execution timing, scope and completion; the owners below supply decisions. Apply the guidance to the user task, not as an exhaustive checklist. Existing repository rules and named exceptions govern values; cases explain judgment and do not define coverage.
-## Architecture prerequisites
+## Required review loop
-Component structure, state flow, and effect usage follow the architecture rules; read them before redesigning a component:
+Layout, copy, icons, styling and interaction changes trigger this loop without a separate review request. Behavior-only edits include affected loading, error, disabled, expanded and focus states. Documentation-only changes and refactors with evidence of unchanged rendering do not need new captures; state that basis.
- [packages/client/AGENTS.md](../../../packages/client/AGENTS.md) — Slot and props discipline, reactive read, export, ctx, and layering rules.
+1. **Before coding, make the design decisions.** Name the user task, affected page or modal, semantic groups, shared alignment references and intended group separation. Select existing components and variants, read applicable owners below, and identify relevant states and consumers using the [impact scope](../../../docs/cookbook/reviewing-ui-design.md#review-scope). Record these choices and planned evidence in a few task-note sentences. Preserve starting source and images; uncommitted UI is not represented by `HEAD`. New UI can use a sketch and established sibling as its starting reference; label them honestly.
- [Client component rules](../../../docs/defensive-patterns/client-components.md) — those requirements stated with the defects they prevent.
+2. **Implement using those decisions.** Reuse the selected components and existing values. Check group structure and shared axes before optical detail. For sidebar work, apply the [master design baseline](../dsh-ui-alignment/SKILL.md#sidebar-design-baseline), including its deliberate differences between roles and states. Expand scope when a shared consumer, neighbor or state can change. Batch coherent edits before recapturing; do not run a full-product audit for each CSS change.
 3. **Before completion, inspect the final rendered result.** Verify affected relationships and behavior in the assembled page or modal, retain comparable before/after evidence for changed positions, and run relevant repository checks. Distinguish inspected, equivalent-by-evidence, unresolved and uninspected scope. Missing required scenes, unresolved defects or failing checks prevent a complete-validation claim; state the gap and next verification.
 4. **Before PR or push, reconcile the cumulative diff.** Check overlapping edits and missing coverage. Reuse evidence while source, dependencies, content, states and capture conditions remain valid; rerun only invalidated or missing checks. Deliver scope, decisions, evidence, results and material gaps.
-## Visual foundation
+Keep the record in the task or local artifacts, not a new tracked checklist per edit. Load applicable owners once while unchanged; retrieve examples only for uncertain decisions. Choose conditions by risk, not every width × theme × state combination or a fixed screenshot count. The [review cookbook](../../../docs/cookbook/reviewing-ui-design.md) owns detailed evidence procedures. Tool success does not judge visual quality.
- **Use existing tokens for color, radius, and spacing.** Before introducing a literal value, search the target page and its nearest established sibling (the Plugins page is the usual reference for full-page surfaces) for the token or value already in use, and adopt it. The same applies to whole treatments — toasts, menus, in-message artifact previews, sidebar tab layout, colors, clearance rules, page padding: reuse the established component or rule wherever one exists instead of inventing a parallel one.
+## Select the rule owners
- **Verify every color in both light and dark mode.** An ink/background pair must stay readable under both themes before it ships. Dimmed tones are the standing counter-example: they suit decorative surfaces, but on text they routinely fall below readability in one theme — never put a dimmed color on text without checking both.
+
- **Font weight tops out at 500 in feature CSS you add or change.** Do not use 600+ for emphasis; differentiate with size or ink instead. The markdown typography tokens owned by ui-theme are the standing exception.
+For layout and grouping changes, read alignment and spacing directly before positioning elements. For other changes, read their applicable owners and preserve existing relationships. Each row has one responsibility; do not copy numeric scales between them.
- **Pick font sizes from the theme typography variables when an existing role matches, otherwise from the page's existing scale.** Parallel content shares one size; never invent a size for a single element, and keep the number of distinct sizes on a page small (13px is the established row/detail size). When the page itself has no precedent, borrow the size and spacing ratios of the most similar existing page or element.
+
- **Icons, text, and neighbouring elements stay proportionate and aligned.** Every element lines up with its siblings along a deliberate axis (baseline, vertical center, or shared edge), and an icon's size stays in proportion to the text beside it; never ship an element that aligns to nothing or visibly outweighs its neighbours.
+| Decision needed before implementation | Owner |
 |---|---|
 | Shared axes, text starts, centering, tree indentation, complete icon boxes | [Alignment](../dsh-ui-alignment/SKILL.md) |
 | Semantic groups, inner/outer gaps, repeated rhythm, section separation | [Spacing and grouping](../dsh-ui-spacing/SKILL.md) |
 | Interface icon selection, drawing, supplied-artwork normalization, style, optical weight, icon/label color | [Icons](../dsh-ui-icons/SKILL.md) |
 | Color, typography and existing treatments | [Visual foundation](references/visual-foundation.md); [Web styling](../../../docs/web-styling.md) owns tokens/materials |
 | Radius tiers, nested/flush/independent corners and exceptions | [Radius standard](../../../docs/ui-radius.md) |
 | Feedback lifetime, loading, overlays, scrolling and platform clearance | [Interaction and feedback](references/interaction.md); [error handling](../dsh-error-handling/SKILL.md) owns failure guarantees |
 | Space allocation, truncation, input capabilities and retained focus | [Responsive UI](../dsh-responsive-ui/SKILL.md) |
 | Official plugin artwork and feature previews | [Official artwork](../dsh-official-plugin-artwork/SKILL.md) |
 | Copy, locale ownership and component semantics | [Prose standard](../dsh-prose-standard/SKILL.md), [locale ownership](../../notes/implemented/architecture/2026-08-23-locale-owned-client-ui-copy.md), [primitives catalog](../../../packages/client/ui-primitives/README.md#component-catalog) |
 | Density, information hierarchy, combined control states and component choice | [Principle reference](../../../docs/ui-design-review-cases.md#density) sections 3–6 |
 ## Reuse before adding
- **Extend an existing component, container, or interaction before creating a new one.** A new capability that fits an existing surface (an extra menu item, a new prop on an existing primitive) beats a parallel element stacked beside it.
+Extend the existing component, container or interaction when the new capability fits it. An extra menu item or primitive prop usually belongs in that owner. Right-sidebar content registers in the existing sidebar. Reuse existing icons first; follow the [icon owner](../dsh-ui-icons/SKILL.md#reuse-existing-icons-first) to decide when a new drawing or normalization is needed.
 - **Icons come from the existing icon library.** Pick the semantically closest existing icon; a new glyph requires designer approval before it lands — when reviewing a PR that adds one, suggest requesting a designer review.
 - **Right-sidebar content registers a slot in the existing sidebar**, never a separate sidebar. Every sidebar tab declares a tab icon matching its meaning.
 - **Icon-only actions whose meaning is not obvious get a Tooltip.** Informational content the pointer must rest on or select uses HoverCard instead. Prefer these shared primitives over ad-hoc title attributes.
-## Feedback surfaces
+Before restructuring components, read [client instructions](../../../packages/client/AGENTS.md) and [client defensive patterns](../../../docs/defensive-patterns/client-components.md) for slots, props, state flow, effects and layering.
-Apply [dsh-error-handling](../dsh-error-handling/SKILL.md#localized-actionable-visible-reports) to failure reports. Choose the surface by the lifetime of the message relative to the surface that produced it:
+## Check the rules together
- **Transient operation outcomes use the app-wide Toast primitive**, not in-place notices, and the toast's state and rendering live in a host that outlives the reporting surface (a `shell.overlay` entry, as RowActionToast does) — a toast rendered by the panel itself unmounts with that panel. A deletion can close the panel or tab that requested it; only a toast held outside that surface survives the close. Report success and failure; do not report still-pending states.
+Inspect the whole composition for context, then the affected cross-group and internal relationships, including distant peers and relevant expanded content. Match both endpoints of each shared axis. Compare complete icon boxes before optical adjustment; keep group separation clear. Geometry must preserve popup and focus visibility; spacing must retain field feedback; narrow layouts must retain actions and drafts. Inspect theme material and platform backdrop where affected. Full-interface claims require all their regions; a fixture or crop establishes only what it renders.
 - **A failed operation keeps the data visible.** A failed deletion keeps its row; the toast announces the failure. Never blank content to show an error for a transient operation.
 - **In-place notices are for states tied to the surface itself**: a query failure with its Retry action, field validation on the form that owns the field. A populated panel keeps a compact notice beside its retained content; only an empty panel centers a full error state.
 - **Error copy is plain language, and short.** No internal jargon or technical nouns unless an error code must be exposed for debugging. Prefer one clear sentence; anything explainable in two sentences must not grow into paragraphs. A Chinese notice of at most two sentences omits the trailing 句号（。）. The notice must not break the existing layout — reserve its space or overlay it; never shift neighbouring elements.
-## Loading states
+## Maintain one owner per rule
- Lists use their skeleton; every other page-level load centers a bare spinner. Never place a spinner in a corner of the page.
+Update the existing owner when a principle changes. Add a focused skill only when it makes a distinct implementation decision; otherwise extend an existing section or reference. Add one routing row here only for a new responsibility. Keep examples in the [case reference](../../../docs/ui-design-review-cases.md), linking to the owner instead of copying its rules. AGENTS files and PR workflows link to this loop and do not repeat its checklist.
 - One loading treatment per page/component — concurrent regions must not each flash their own style.
 - No loading text unless the context needs it (narrow sidebars almost never do).
-## Overlays and menus
+For a rule change, state applicability, decision, exceptions and observable verification in its owner; add or update a case that distinguishes a valid result from a plausible wrong fix. Search other owners for superseded statements. Declare whether existing consumers are being migrated or only future edits must comply. Rule edits do not establish that existing UI already conforms. Add a deterministic gate only for a mechanically decidable invariant; rendered judgment remains part of the development loop. Local review tools read these repository owners and retain the reviewed source and rule revisions; they do not maintain a second standards copy.
 Every menu, popover, and tooltip must be verified for all three before merge:
 - **Dismissable**: outside click (and Escape where focusable) closes it.
 - **Viewport-fitting**: it slides or flips to stay inside the window with an edge margin, and flips only into a side that actually fits (no oscillation when neither side fits).
 - **Unclipped**: it escapes `overflow` ancestors and containing blocks (portal to body where needed) and is never covered by neighbouring elements.
 Scrollbars stay inside their container: use the shared scrollbar styles rather than component-specific selectors, and verify the bar neither overflows the container nor gets clipped by its rounded corners or edges — keep a small inset instead of letting it sit flush against the container edge.
 ## Responsive layouts
 Use [dsh-responsive-ui](../dsh-responsive-ui/SKILL.md) for responsive layouts, mobile and touch detection, text truncation, title wrapping, icon-only controls, and focus during width changes.
 ## Platform window adaptation
 - Any new header element or full page must account for macOS and Windows window chrome. On macOS the titlebar clearance is `--dsh-frame-top-clearance`, consumed by Menu, Modal, and overlay primitives as their top safe margin — **never change the global variable to fix one page**. Add a scoped `[data-platform='darwin']` override on the page's own inset instead, and assert the override in the page's stylesheet spec.
 - State the intended total offset (clearance + page inset) when reviewing, so two pages aligning to "the same top spacing" agree on the sum, not just one addend.
 ## Spacing review
 - Review every changed region for gaps: nothing sits flush against its neighbour without an intentional gap, and adjacent icons and elements keep the region's established spacing.
 - Prefer symmetry for parallel elements; an unexplained one-off gap or offset usually signals a missed shared value.
 - **For complex pages and containers, establish shared horizontal and vertical alignment axes before adjusting local spacing.** Consider hover, selected, and expanded/collapsed states, as well as the overall relationship with adjacent panels and other page elements. Choose from the following references according to layout similarity:
  - **Sidebar:** align corresponding text starts and leading icons across vertically stacked rows. Align hover and selected row backgrounds with the buttons above the list to maintain visual balance.
  - **Plugins page:** keep content left-aligned along a shared edge. List-row hover backgrounds may extend beyond that edge while the content stays in place.
  - **Conversation and right-sidebar headers:** align the first header rows across both panels and match their heights. Apply the same rule to the second rows, and align corresponding underlines and dividers on shared horizontal baselines.
 ## Design review escalation
- A PR with extensive UI changes, or any clearly user-perceivable change to UI or interaction, must get a designer or product review. When no approver holds that role, suggest requesting one from the design/product reviewers (roster as of 2026-09: yx zhang, yifffan, zhangziya, gaokaige; update this list here when membership changes).
+Obtain designer or product review before landing new pages or interaction patterns, broad shared-component or global visual changes, and unresolved design tradeoffs. Routine local corrections use this loop without another human checkpoint. Explicit independent reviews and periodic human audits can widen scope and feed recurring misses into owning rules; neither replaces development-time decisions or creates an automatic schedule.
@@ -0,0 +1,31 @@
 # Interaction and feedback
 ## Feedback surfaces
 Apply [dsh-error-handling](../../dsh-error-handling/SKILL.md#localized-actionable-visible-reports) to failure reports. Choose the surface by the lifetime of the message relative to the surface that produced it:
 - **Transient operation outcomes use the app-wide Toast primitive**, not in-place notices, and the toast's state and rendering live in a host that outlives the reporting surface (a `shell.overlay` entry, as RowActionToast does) — a toast rendered by the panel itself unmounts with that panel. A deletion can close the panel or tab that requested it; only a toast held outside that surface survives the close. Report success and failure; do not report still-pending states.
 - **A failed operation keeps the data visible.** A failed deletion keeps its row; the toast announces the failure. Never blank content to show an error for a transient operation.
 - **In-place notices are for states tied to the surface itself**: a query failure with its Retry action, field validation on the form that owns the field. A populated panel keeps a compact notice beside its retained content; only an empty panel centers a full error state.
 - **Error copy is plain language, and short.** No internal jargon or technical nouns unless an error code must be exposed for debugging. Prefer one clear sentence; anything explainable in two sentences must not grow into paragraphs. A Chinese notice of at most two sentences omits the trailing 句号（。）. The notice must not break the existing layout — reserve its space or overlay it; never shift neighbouring elements.
 ## Loading states
 - Lists use their skeleton; every other page-level load centers a bare spinner. Never place a spinner in a corner of the page.
 - One loading treatment per page/component — concurrent regions must not each flash their own style.
 - No loading text unless the context needs it (narrow sidebars almost never do).
 ## Overlays and menus
 Every menu, popover, and tooltip must be verified for all three before merge:
 - **Dismissable**: outside click (and Escape where focusable) closes it.
 - **Viewport-fitting**: it slides or flips to stay inside the window with an edge margin, and flips only into a side that actually fits (no oscillation when neither side fits).
 - **Unclipped**: it escapes `overflow` ancestors and containing blocks (portal to body where needed) and is never covered by neighbouring elements.
 Scrollbars stay inside their container: use the shared scrollbar styles rather than component-specific selectors, and verify the bar neither overflows the container nor gets clipped by its rounded corners or edges — keep a small inset instead of letting it sit flush against the container edge.
 ## Platform window adaptation
 - Any new header element or full page must account for macOS and Windows window chrome. On macOS the titlebar clearance is `--dsh-frame-top-clearance`, consumed by Menu, Modal, and overlay primitives as their top safe margin — **never change the global variable to fix one page**. Add a scoped `[data-platform='darwin']` override on the page's own inset instead, and assert the override in the page's stylesheet spec.
 - State the intended total offset (clearance + page inset) when reviewing, so two pages aligning to "the same top spacing" agree on the sum, not just one addend.
@@ -0,0 +1,7 @@
 # Visual foundation
 - **Use existing tokens for color, radius, and spacing.** Before introducing a literal value, search the target page and its nearest established sibling (the Plugins page is the usual reference for full-page surfaces) for the token or value already in use, and adopt it. The same applies to whole treatments — toasts, menus, in-message artifact previews, sidebar tab layout, colors, clearance rules, page padding: reuse the established component or rule wherever one exists instead of inventing a parallel one.
 - **Verify every color in both light and dark mode.** An ink/background pair must stay readable under both themes before it ships. Dimmed tones are the standing counter-example: they suit decorative surfaces, but on text they routinely fall below readability in one theme — never put a dimmed color on text without checking both.
 - **Font weight tops out at 500 in feature CSS you add or change.** Do not use 600+ for emphasis; differentiate with size or ink instead. The markdown typography tokens owned by ui-theme are the standing exception.
 - **Pick font sizes from the theme typography variables when an existing role matches, otherwise from the page's existing scale.** Parallel content shares one size; never invent a size for a single element, and keep the number of distinct sizes on a page small (13px is the established row/detail size). When the page itself has no precedent, borrow the size and spacing ratios of the most similar existing page or element.
 - Apply [alignment](../../dsh-ui-alignment/SKILL.md) and [icons](../../dsh-ui-icons/SKILL.md) to icon/text relationships.
@@ -39,6 +39,7 @@ description: Use when reviewing a pull request in the deepseek-harness repo —
 ## Manual checks
 - **UI review coverage:** apply the [required review loop](../dsh-client-ui-ux/SKILL.md#required-review-loop) to the cumulative visible diff. Verify scope selection, affected shared consumers, final evidence and gaps; request missing affected-state evidence rather than an unrelated full-product audit. Existing valid checks need not be repeated.
 - **Intent and interface contracts:** trace both sides of every changed interface. Confirm the implementation matches the PR and any Agent Note, including errors, cancellation, ownership, and disposal.
 - **Error handling:** apply [dsh-error-handling](../dsh-error-handling/SKILL.md) to changed failure paths, including their state guarantees and final user-visible reports. Reject catch-and-continue unless the state owner establishes that subsequent work's preconditions hold, including after recovery.
 - **Lifecycle and concurrency:** for async setup, callbacks, processes, or teardown, apply [defensive-patterns/general.md](../../../docs/defensive-patterns/general.md). Check races before publication, cancellation during awaits, independent error reporting, callback containment, ownership before reentry, complete detach cleanup, and quiescent disposal.
@@ -7,6 +7,8 @@ description: Draw and review official DeepSeek Harness plugin icons and optional
 Draw recognizable artwork that belongs beside the existing official icons. Official and official experimental plugins share this visual language; the UI label communicates experimental status. This guidance does not replace designer approval.
 When reviewing the containing page, use the [UI review baseline](../../../docs/ui-design-review-cases.md#review-baseline) to combine artwork balance with its tile, label, neighboring cards and theme material. Keep package artwork distinct from action icons: coherent optical weight does not require equal drawing bounds, monochrome fills or identical geometry across those roles.
 ## Optional feature previews
 Before drawing a larger image for the top of an official bundle's detail document, read and follow [adding a plugin feature preview](../../../docs/cookbook/adding-a-plugin-preview.md). It owns optionality, image count, design canvas, position, language variants, file location, and acceptance. The guide also owns the embedded-raster exception for SVG previews; small icons remain geometry-only. The icon dimensions below do not apply to previews. Inspect the real feature and preserve its produced assets.
@@ -14,7 +16,7 @@ Before drawing a larger image for the top of an official bundle's detail documen
 ## Establish the subject
 - Inspect the actual feature, its output, and its owning manifest before drawing. A badge-producing skill may need a tag, not a medal. Reuse designer-supplied assets; do not invent a brand mark or change product names, identifiers, or unrelated icons without approval.
- Read the [existing artwork](../../../packages/client/ui-primitives/src/plugin-artwork.tsx) and the nearest relevant package SVGs. Borrow one coherent treatment, not every reference's effects. Action icons remain with [dsh-client-ui-ux](../dsh-client-ui-ux/SKILL.md#reuse-before-adding).
+- Read the [existing artwork](../../../packages/client/ui-primitives/src/plugin-artwork.tsx) and the nearest relevant package SVGs. Borrow one coherent treatment, not every reference's effects. Action icons remain with [the interface icon skill](../dsh-ui-icons/SKILL.md).
 - Check every affected entry, list, detail, and component row. Bundle artwork and a component's name and icon can have separate metadata owners; changing one does not update the other.
 ## Draw and refine
@@ -33,6 +33,7 @@ When the outgoing change adds or changes a resource-owning or asynchronous test,
 - **Package or script behavior:** run the owning Vitest file or focused test name. Add adjacent package tests when a shared contract changes; leave repository-wide coverage to CI unless the change is genuinely cross-cutting or the user requests it.
 - **Remote mock typing:** unbuilt `any` is an explicit local fallback, not strict evidence. Run `pnpm run typecheck` before handing off Remote/mock changes; rebuild missing, stale, or partial generated declarations before diagnosing remaining errors. Keep the exception in the [test proxy](../../../packages/test-support/remote-mock/README.md#remote-proxy), never in production Remote types, ambient flags, or copied signatures.
 - **Documentation, Agent Notes, catalogs, or doc-linked comments:** run `pnpm run doc-sync`; run full lint when the documentation workflow requires it.
 - **User-visible UI:** reconcile the outgoing diff with the [required review loop](../dsh-client-ui-ux/SKILL.md#required-review-loop). Check affected-page scope, final visual evidence, unresolved gaps and interactions between cumulative edits; reuse evidence that remains valid rather than restarting a full-product review. Passing tests alone do not establish visual acceptance.
 - **Model-, editor-, CLI-, or terminal-visible output:** run the focused keyless snapshot or real runnable-example scenario that owns the output.
 - **Expected-output placement:** a test whose selected recorded Session generation is replay input and expected persisted output belongs under top-level `snapshots/`, with `snapshot.yml` naming its shipped `dsh` profile and composition/header pin. Canonical parent files are `session[.vN].jsonl`, children are `session.<ordinal>[.vN].jsonl`, and the harness selects the highest generation per role. ARIA, geometry, generator, CLI, and unit expectations without that Session round trip stay beside their owning test under `tests/expected/`; do not place them in `snapshots/` or give them a `*.snapshot.ts` owner. Use the owning `test:expected`, `test:web`, or `test` lane.
 - **Profile and configuration placement:** cross-package behavior of a shipped `dsh` profile belongs under `apps/cli/tests/profiles/`; a package-specific Loader composition belongs under that package's `tests/fixtures/`. User-facing optional overlays live under `apps/cli/config/examples/` and pair with a guide under `docs/user/`.
@@ -5,6 +5,8 @@ description: Use when designing, implementing, or reviewing responsive client la
 # Responsive client UI
 For visual reviews, select the [impact scope](../../../docs/cookbook/reviewing-ui-design.md#review-scope), then apply these behavioral requirements and the [UI review baseline](../../../docs/ui-design-review-cases.md#review-baseline). Compare affected wrapping and layout relationships in the whole page or modal's context while preserving drafts, focus and action access. Inspect all regions for an explicit full-interface review. Examples do not define coverage; fitting the viewport alone is insufficient.
 ## 1. Minimum viewport
 Use a viewport width of 390 CSS px as the primary acceptance minimum. There must be no unintended overlap, clipping, page-wide horizontal scrolling, or inaccessible primary actions. Below 390px, layout requirements may be relaxed.
@@ -0,0 +1,50 @@
 ---
 name: dsh-ui-alignment
 description: Design or review DSH layout alignment, shared text columns, icon and label placement, tree indentation, and centering across groups. Apply before positioning elements and when checking rendered results.
 ---
 # UI alignment
 Use this decision guidance within the [UI development loop](../dsh-client-ui-ux/SKILL.md#required-review-loop). Apply it to the affected groups in their page or modal context; examples are not a coverage list.
 Align elements that the reader compares as peers, including the space reserved for optional icons or actions.
 ### Layout structure first, visual calibration second
 An icon's complete box includes intentional whitespace around its drawing and is a valid layout unit. Distinguish the interaction target, painted button surface, icon box and drawn contour: enlarging the target must not move the icon box, and internal whitespace must not be removed merely because painted pixels miss a guide. Compare shared slots, text columns and gaps first, then inspect balance at the intended size. Neither aligning every differently shaped contour from a screenshot nor accepting visibly unbalanced results solely because boxes agree is sufficient.
 Trace misalignment to containers, slots and unintended overrides first. Once the structure is sound, distinguish an inconsistent library glyph from an optical adjustment needed by a particular composition. The icon owner handles the former; justify and scope the latter, then inspect comparable uses. Preserve the owning design’s hierarchy and indentation. A child icon may continue the parent text column when that is the intended tree relationship; DOM nesting alone does not establish it. When comparing a bare icon with a bordered control, do not treat extra hit padding as a common visible edge. Small contour differences caused by intentional whitespace are not automatically defects.
 An inline SVG’s `vertical-align: middle` uses the baseline and font x-height; it does not establish centering with adjacent text. Identify the font, size, line height, and complete icon box before choosing a text metric as the reference, then check CJK, Latin, monospace text, and wrapping. Do not turn a multiline link into an unwrappable flex unit to center its icon; verify the adjustment across fonts.
 ### Choose both the object and the axis
 Specify what is aligning to what. Distinguish the element's layout box, its visible glyph or text, its clickable area, and the container that defines its position. Equal padding does not guarantee equal text starts; equal SVG dimensions do not guarantee equal visible centers. An icon and label form a unit, repeated units form a column, and corresponding columns can continue across section boundaries.
 | Alignment | Use it for | Judge the actual relationship | Common mistake |
 |---|---|---|---|
 | Left edge | Navigation labels, list titles, field labels, reading content | Same-role text starts on one deliberate axis, including across groups | Every component has its own plausible but different inset |
 | Horizontal center | A standalone primary button or short empty-state stack | Center the icon-plus-label or full stack in the named container | Center the label alone and attach an icon outside it |
 | Vertical center | A single-line icon/label row or peer toolbar controls | Visible centers balance; the whole clickable unit keeps a stable height | Equal CSS heights hide different SVG whitespace or line boxes |
 | Baseline / first line | Mixed text sizes, multiline labels with leading icons | Text baselines agree; an icon belongs to the intended first line | Center an icon beside the entire multiline paragraph |
 | Two edges | Title/action rows and left/right composer groups | Left group follows the content edge; right group follows the trailing edge | Distribute every icon across the available width |
 | Repeated columns | Action clusters, timestamps, file rows | Corresponding slots share centers or edges across rows | Only the last icon aligns; preceding icons drift |
 For left-to-right Chinese and English navigation, identify the leading icon center, text start and trailing controls by role. Continue an axis across groups only where the owning design establishes that relationship. Headings, account avatars and expandable search controls can use different geometry. DOM nesting alone neither requires nor forbids an indent.
 ### Sidebar design baseline
 Use the current master sidebar design as the reference for layout, spacing, alignment and states. Verify the base revision and record it with the review evidence. Read the [sidebar](../../../packages/client/ui-sidebar/README.md), [workspace](../../../packages/client/ui-workspace/README.md) and [account](../../../packages/client/ui-settings-account/README.md) owners and their styles before proposing a correction. Keep their shared spacing variables, icon slots and painted insets; compare hover and selected backgrounds with the intended button edges separately from content axes.
 Compare same-role rows and preserve their title starts when actions appear. Do not force the signed-in account row onto the navigation text axis, or the workspace header’s search/filter/add controls onto conversation action columns. Search expansion and collapsed-rail states have their own layout. A retained icon correction does not authorize changing these relationships. Inspect the assembled sidebar in the relevant states; an older case image or isolated row cannot override the baseline.
 For other layouts, preserve established cross-panel relationships: plugin content shares its reading edge even when hover paint extends beyond it; conversation and right-sidebar header rows share their intended heights and horizontal baselines. Choose the relationship from the composition, not merely from similar CSS values.
 Centering always has a reference rectangle. A centered button uses its own bounds; a welcome area uses the main pane; an empty state generally uses the content space remaining below the page heading and filters. A fixed top margin is not vertical centering. If a short window cannot contain that group, preserve scroll access and use a compact top-aligned layout instead of clipping it. Two-edge alignment also operates on groups: keep each group's internal gaps fixed as the space between groups grows.
 Change element size when that is the coherent way to obtain alignment. Normalize peer button slots and icon containers before adding individual offsets. Then apply a small optical correction only when the drawn shape still requires it, and verify other uses. Keep click targets usable; shrinking them to force alignment or using transforms to conceal inconsistent parent layout is not an acceptable fix.
 Check neighboring groups with [spacing](../dsh-ui-spacing/SKILL.md). Changing a gap must preserve the chosen reference axes.
 See [worked examples](../../../docs/ui-design-review-cases.md#alignment) when the relationship is unclear.
@@ -0,0 +1,76 @@
 ---
 name: dsh-ui-icons
 description: Reuse existing DSH interface icons first; draw missing glyphs, normalize user-supplied artwork, or review system style, optical size, clarity, and text relationships. Use for action, navigation, file and status icons; official plugin artwork has its own skill.
 ---
 # UI icons
 Use this decision guidance within the [UI development loop](../dsh-client-ui-ux/SKILL.md#required-review-loop). Apply it to the affected groups in their page or modal context; examples are not a coverage list.
 ## Reuse existing icons first
 Before drawing or adding an icon, search the existing library and comparable UI for the intended meaning, component, size and weight variants. If an existing glyph expresses the action or state clearly, use its shared component. A request to add an icon to a feature does not by itself call for a new drawing. Do not copy its SVG into a feature-local implementation or create a near-duplicate merely to make that feature look different.
 Draw a new glyph only when existing artwork cannot express the required meaning or the user explicitly requests a distinct design. Identify the closest existing alternatives and explain the unmet meaning or requested design difference before drawing. A size, color or placement mismatch alone is a reason to inspect the supported variant and consumer layout, not to invent another glyph. Follow the authoring workflows below for requested drawing or adaptation. A new glyph requires designer approval before landing; that requirement does not prevent preparing a requested draft. Do not silently redraw an existing glyph to fix a single consumer.
 The [primitives catalog](../../../packages/client/ui-primitives/README.md#component-catalog) and icon source own the available variants and stroke values. [Official plugin artwork](../dsh-official-plugin-artwork/SKILL.md) owns package artwork, not action icons.
 ## System style
 Design interface glyphs as a coherent tool-oriented set: minimal, geometric, functional, balanced, precise and technical. Prefer familiar action, navigation and workflow meanings that read quickly in professional software. Avoid cute, playful, hand-drawn or decorative treatments and illustration-like detail. Match neighboring library glyphs in contour, line endings, joins, optical weight, whitespace, proportions and complexity; a supplied reference guides the requested meaning and distinctive form within this system.
 Use simple lines, circles, rectangles and summarized curves, with consistent line weight within each variant. Follow the fixed Regular and Medium strokes defined below; the system has both weights. Use restrained corner rounding that matches the closest peers. Around 1px at a 16px design size is a starting point for a small softened corner, not a radius to impose on every turn, circle or existing glyph. Preserve useful sharp corners and avoid an overly rounded appearance.
 Default to monochrome outline artwork inheriting `currentColor`, without gradients, shadows, textures or 3D effects. Retain purposeful filled silhouettes, status dots, selected-state marks and knockout shapes already supported by the library. File, site, plugin and brand artwork follow their own roles and palette rules. Do not remove meaningful fill or color merely to make these categories resemble line icons.
 Balance the visible weight horizontally and vertically through structure, whitespace and line distribution; geometric symmetry is not required. Avoid accidental tilt, a top-heavy silhouette or decorative motion. Keep direction when it carries meaning, such as an arrow. Simplify redundant detail without losing recognition, and do not force every subject into a single closed geometric outline.
 For complex meanings, use relationships between a few elements: open or broken contours, controlled gaps, crossings, overlap, nesting and foreground/background order. Break an obscured line where needed to clarify which element is in front. These relationships must remain legible at the intended small size, without accidental tangencies, dark knots or gaps that disappear after rasterization. Add contour detail only when it improves recognition.
 ## Draw a new icon
 Enter this workflow only after applying the reuse rule above. Establish the intended meaning, placement, actual sizes, neighboring icons and required states from the request and available UI context. Ask only when missing information would change the meaning or design. Use the closest library artwork as references for the new design.
 Produce editable SVG geometry with the system style above. Develop the silhouette at the intended size, then tune internal gaps, optical center and weight. Provide Regular and Medium variants for shared line icons, preserving the same construction; intentional fill-only variants can share geometry. Follow the owning component and theme conventions rather than introducing consumer-specific stroke or scale overrides.
 Use the verification section below. Deliver the editable artwork and a rendered comparison beside the chosen library peers, including the icon with its label or control when relevant. Explain the semantic choice and any unresolved alternative. Keep concept drafts local; register reusable components and update their owning documentation when implementation is in scope. Distinguish a proposal ready for review from an approved glyph ready to land.
 ## Normalize user-supplied artwork
 Inspect the supplied SVG or image and establish its meaning, recognizable features and intended use before changing it. Check whether an existing library glyph already serves the product need. When the user specifically asks to normalize their own drawing, preserve that task and show the existing equivalent as a reference rather than silently substituting it. Preserve the original for comparison. Separate technical corrections such as canvas whitespace, scale, stroke, color inheritance and placement from changes to silhouette, detail or visual metaphor. Preserve the recognizable form unless the requested normalization requires simplification; identify any such design change in the result.
 For SVG, inspect its paths, transforms, fills, strokes and internal references. Resolve unwanted scaling and filled line contours using the clarity rules below. A raster reference may need reconstructed vector geometry; do not trace antialiasing or compression artifacts into paths, and identify details that were interpreted. If a defining detail cannot be recovered, ask about that detail rather than presenting an invented feature as part of the original.
 Apply the same style and verification criteria as new artwork. Deliver the original and normalized versions under identical rendering conditions, alongside established peers and at the intended use size. Include editable SVG and briefly distinguish technical fixes from design changes. Keep source artwork changes separate from corrections to an individual consumer's layout.
 ## Placement and use
 Review the layout box, the painted glyph, and its relationship to neighbouring text as separate properties.
 Judge four layers separately: clickable target, visible button base, icon slot, and painted glyph. Peer targets and bases can be equal while different glyphs need slightly different drawing bounds. Neither equal SVG width nor equal ink area establishes equal perceived size. Compare stroke weight, internal whitespace, silhouette, and center at the size actually used, with the adjacent text present.
 First fix container layout and unintended CSS overrides. Correct a library glyph only if its imbalance follows it across uses; a single consumer's wrong size belongs to that consumer. A native file icon and a monochrome folder outline require a deliberate optical relationship even when their nominal boxes agree. Status dots, logos, and decorative illustrations are different roles and must not be normalized to toolbar icons.
 An icon and label communicating one action normally share a foreground role and state changes. Search icons and placeholders form one prompt; typed text and an independent clear action can differ. Check actual opacity, stroke and background in both themes. Status, warning and brand roles can justify a different color.
 An icon-only action with unclear meaning gets the shared Tooltip; informational content that must be hovered or selected uses HoverCard. The [responsive skill](../dsh-responsive-ui/SKILL.md) owns mobile tooltips and when labels may collapse. Every right-sidebar tab declares a meaningful icon.
 [Alignment](../dsh-ui-alignment/SKILL.md) owns icon-plus-label positioning; [spacing](../dsh-ui-spacing/SKILL.md) owns the gap. Preserve accessible labels and focus when changing presentation.
 See [worked examples](../../../docs/ui-design-review-cases.md#icon-optics) when the relationship is unclear.
 ## Optical size and clarity before implementation
 Use 14px Regular line icons with fixed 1px strokes in ordinary menus; compact menus retain their 12px treatment. Permission-selector triggers and settings-navigation peers use 16px slots; permission-menu rows retain the ordinary 14px treatment. Choose size for the owning control and compare candidates together at that size, weight, foreground and background, including their labels. Use a representative outlined circle and rectangular control as references. Open silhouettes can need more extent than dense filled shapes; chevrons, drag handles and status dots retain their supporting roles. Never normalize all glyphs by bounding-box area or force every path to fill its view box.
 When an imbalance repeats across consumers, adjust the owning artwork once. Inspect every library glyph and both weights after a set-wide change, including unchanged glyphs, inline composites, and feature-local duplicates. Consolidate duplicate semantic artwork where an existing shared glyph serves the same role. Keep file, site, plugin and brand artwork in separate comparison groups with their own intended sizes. Preserve an inventory so an omitted family cannot be mistaken for a completed review.
 Diagnose softness in this order: rendered CSS dimensions and ancestor transforms; source view box and drawing bounds; stroke versus filled contour; final placement on the device pixel grid; then color and opacity. A non-16 view box is not itself defective. Neither inline SVG nor a sprite is inherently sharper: compare the same artwork through both paths before changing the rendering architecture.
 Regular strokes remain 1 CSS pixel and Medium strokes 1.3 CSS pixels when the icon is resized. Use non-scaling strokes for line artwork, including inline composites. A filled outline ignores stroke width; if it represents an ordinary line icon, convert that contour to a real stroke when consistent weight across sizes is required. Preserve intentional filled silhouettes and knockout marks rather than applying the rule indiscriminately.
 For a horizontal or vertical stroke, inspect its painted edges at the actual device pixel ratio (DPR), after all view-box and CSS scaling. Integer source coordinates alone do not establish crispness; center position and stroke width jointly determine edge coverage. At DPR 2 a 1px stroke can occupy two solid device pixels; a fractional offset can add grey edge pixels. Round positioned overlays in device pixels when their layout otherwise places crisp artwork between pixels. Check that this does not change anchoring or viewport containment. Keep antialiasing on curves and diagonals; do not globally round path points or use `crispEdges` to conceal a placement error. A 1.3px stroke legitimately has partial edge coverage.
 ## Verification and handoff
 Verify light and dark themes at DPR 1 and 2, at 14px and 16px and any larger size the changed consumer uses. Keep a working-tree baseline and compare final raster output at actual size; enlarged pixel views only diagnose edge coverage. Check semantic recognition, consistency with peers, clipping, center, internal gaps, fixed stroke weight and neighboring text. For a full-set review, deliver every final glyph side by side, label changed and unchanged entries, and make the before/after comparison use identical rendering conditions.
@@ -0,0 +1,29 @@
 ---
 name: dsh-ui-spacing
 description: Design or review DSH semantic grouping, internal and external spacing, repeated rhythm, and section separation. Apply before choosing gaps and when content wraps or expands.
 ---
 # UI spacing and grouping
 Use this decision guidance within the [UI development loop](../dsh-client-ui-ux/SKILL.md#required-review-loop). Apply it to the affected groups in their page or modal context; examples are not a coverage list.
 Distance should explain which text, input, and action belong together before the reader needs a border.
 ### Identify the group before choosing the gap
 Elements belong together because they describe one object, complete one action, or form one repeated unit. DOM siblings, equal backgrounds, or one React component do not establish that relationship. Write the grouping in ordinary language first: “title and description introduce this section”; “these three actions operate on this conversation”; “these cards form the members section, which is separate from the tasks section.” Then position the groups.
 A group can contain smaller groups. In a model form, a checkbox and its label form an option; several options form an input-type field; that field joins other fields in one model; multiple models form the model list. Check spacing at each level. A very wide gap inside a higher-level layout does not require every lower-level gap to become larger.
 For comparable neighboring groups without an explicit divider, the visible separation between groups must be greater than the gap joining elements inside each group. Equality is a lower bound against reversal, not the target when space is carrying the hierarchy. Repeated groups with the same composition share the same internal gap pattern, padding, and alignment. Different label lengths do not justify unrelated spacing rules.
 As a group gains subgroups, wrapping, secondary metadata, or independent operations, its internal structure demands more separation from the next group. Increase the enclosing section gap enough to preserve that distinction. Do not compute space from card area or multiply every margin: a compact icon-and-label pair and a section of multi-line cards need different levels of spacing. A divider or distinct surface can reinforce the boundary, but it must not leave a heading visually attached to the preceding group.
 Judge visible whitespace as well as CSS values. Button padding, line-height, glyph whitespace, borders, and margins all contribute. A declared 16px/8px margin pair can still produce an unclear heading relationship. At normal display size, the heading should appear closer to the content it introduces than to the previous section; an explanatory label should have one unambiguous owner.
 Preserve the [sidebar design baseline](../dsh-ui-alignment/SKILL.md#sidebar-design-baseline) when reviewing its groups, including state-specific spacing. Do not replace its established rhythm with a case diagram’s dimensions.
 Use existing page spacing and [style tokens](../../../docs/web-styling.md); this skill does not create a numeric scale. Check shared axes with [alignment](../dsh-ui-alignment/SKILL.md).
 See [worked examples](../../../docs/ui-design-review-cases.md#grouping) when the relationship is unclear.
@@ -40,6 +40,7 @@ apps/web/dist/
 .artifacts/
 .dsh-build/
 .dsh-report/
 .ui-review/
 .playwright-mcp/
 .orig
 .worktrees/
@@ -157,6 +157,7 @@ Real-API tests/demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`, and
 - **Create Agent Notes only for durable decision rationale;** mechanical/local edits are exempt, including local UI changes ([scope](.agents/notes/README.md#when-to-write-one)). Archived notes are frozen: never edit or treat them as current authority ([archive policy](.agents/notes/README.md#archiving-and-deletion)).
 - **Official plugin artwork:** use [dsh-official-plugin-artwork](.agents/skills/dsh-official-plugin-artwork/SKILL.md) for official and official experimental plugin icons; obtain designer approval before landing new glyphs.
 - **Client UI copy is locale-owned.** Route product text through typed dictionaries and `t` or localized primitive props; `verify-client-ui-i18n` rejects hardcoded copy ([decision](.agents/notes/implemented/architecture/2026-08-23-locale-owned-client-ui-copy.md)). English copy, including plugin titles, uses sentence case ([rule](.agents/skills/dsh-prose-standard/SKILL.md#required-coverage-by-prose-location)).
 - **UI changes:** read the [UI development skill](.agents/skills/dsh-client-ui-ux/SKILL.md) before coding; select applicable rules and design relationships, then follow its scoped verification through handoff and PR.
 - **Testing policy** — [docs/testing.md](docs/testing.md). Every non-trivial model- or product-user-visible change updates a keyless recorded-session snapshot; [snapshot ownership](snapshots/AGENTS.md) reserves the top-level tree for session-driven cases and keeps other expected output owner-local. Fixtures replay on macOS/Linux; fix fixtures, not normalizers.
 - **Design each tool's UI presentation up front.** Host presenters stay pure; Web cards derive from raw events and persisted result metadata ([cookbook](docs/cookbook/adding-a-tool.md)).
 - **Plan unit, e2e, and snapshot coverage** for capability seams, lifecycle paths, and transcript output; include missing snapshot-harness support in the same change.
@@ -0,0 +1,15 @@
 <svg xmlns="http://www.w3.org/2000/svg" width="1000" height="540" viewBox="0 0 1000 540" role="img">
 <title>Sidebar alignment follows roles and states</title>
 <rect width="1000" height="540" fill="#fff"/>
 <g font-family="Arial,sans-serif" fill="#263044">
 <text x="28" y="34" font-size="17">ALIGNMENT · schematic only; use the recorded master design for dimensions</text>
 <rect x="28" y="60" width="430" height="450" rx="16" fill="#f8f9fb" stroke="#d9dfe7"/>
 <rect x="52" y="80" width="382" height="46" rx="12" fill="#fff" stroke="#d9dfe7"/>
 <text x="243" y="109" text-anchor="middle" font-size="18">＋ New conversation</text>
 <g fill="none" stroke="#647184" stroke-width="2"><circle cx="74" cy="160" r="7"/><circle cx="74" cy="200" r="7"/><rect x="67" y="300" width="14" height="12" rx="2"/></g>
 <g font-size="17"><text x="98" y="166">Navigation</text><text x="98" y="206">Navigation</text><text x="52" y="268" fill="#707b8a">Workspaces</text><text x="98" y="312">Project</text><text x="98" y="352">Conversation</text><text x="98" y="392">Conversation</text></g>
 <g fill="none" stroke="#647184" stroke-width="2"><circle cx="333" cy="262" r="6"/><circle cx="374" cy="262" r="6"/><circle cx="415" cy="262" r="6"/><circle cx="341" cy="346" r="5"/><circle cx="375" cy="346" r="5"/><circle cx="409" cy="346" r="5"/></g>
 <path d="M74 142V218 M98 142V218 M74 290V407 M98 290V407" stroke="#20826a" stroke-dasharray="5 5" fill="none"/>
 <path d="M52 432H434" stroke="#d9dfe7"/><circle cx="76" cy="472" r="17" fill="#d9e4ee"/><text x="110" y="478" font-size="17">Signed-in account</text>
 <g font-size="19"><text x="500" y="108">Center the primary action as a unit.</text><text x="500" y="177">Continue axes across intended peers.</text><text x="500" y="267">Header and row controls have distinct roles.</text><text x="500" y="307">Search expansion changes header geometry.</text><text x="500" y="386">Compare paint and hit targets separately.</text><text x="500" y="476">Keep the account row’s own geometry.</text></g>
 </g></svg>
@@ -0,0 +1,55 @@
 # Bilingual-pair consistency record for reviewing-ui-design.md (docs/i18n/README.md): per heading
 # section, a hash of its English and Chinese blocks outside code blocks and generated regions.
 # After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/cookbook/reviewing-ui-design.md
 /:
  en: 7a1a3135b7683184
  zh: b518133afc663a6e
 /cookbook-review-a-ui-design:
  en: d42b121ca63177aa
  zh: 68b637fae3252c7b
 /cookbook-review-a-ui-design/summary:
  en: e1512525090123b8
  zh: 4a6749841c93917b
 /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: b43b99e09f5c5c5c
  zh: f95c8f7006661c1a
 /cookbook-review-a-ui-design/1-define-the-page-or-modal-in-scope/select-scope-by-visual-impact:
  en: 03e253193982403b
  zh: 5b1e10220ffbe53d
 /cookbook-review-a-ui-design/2-inspect-the-task-and-its-implementation:
  en: 33305b3aeaf47316
  zh: d9fc73f001d6acca
 /cookbook-review-a-ui-design/2-inspect-the-task-and-its-implementation/reconcile-the-baseline-across-the-whole-interface:
  en: 76d008d0bac44f1f
  zh: 2357d78f350b5540
 /cookbook-review-a-ui-design/2-inspect-the-task-and-its-implementation/make-the-relationships-explicit:
  en: 2a2e815b1b0e74e9
  zh: 57f025943a700552
 /cookbook-review-a-ui-design/2-inspect-the-task-and-its-implementation/keep-a-coverage-record:
  en: 4fb9380f3ceeb4bb
  zh: 4ce932dfc8ae84b2
 /cookbook-review-a-ui-design/3-preserve-the-starting-point:
  en: 193e00e7761fc560
  zh: cc704fc699413de6
 /cookbook-review-a-ui-design/4-change-the-smallest-responsible-component:
  en: 048668959e84707b
  zh: 3e3478b0c313ed43
 /cookbook-review-a-ui-design/5-verify-behavior-and-comparable-images:
  en: ed5690014ab05334
  zh: 3f25d7f5118dd2a6
 /cookbook-review-a-ui-design/6-deliver-the-complete-evidence:
  en: 7cf5020be5145c13
  zh: 810942039512af69
 /cookbook-review-a-ui-design/6-deliver-the-complete-evidence/comparison-delivery-and-cumulative-changes:
  en: a6c7ea042ef480d8
  zh: f638f58639cc6888
 /cookbook-review-a-ui-design/further-exploration:
  en: 98ac3512211d94ae
  zh: 055418a72f29a15b
 /cookbook-review-a-ui-design/dev-note:
  en: b75c8458928b72b9
  zh: 003ba4e17b4b5269
@@ -0,0 +1,162 @@
 ---
 description: "Review a DSH page or modal as a whole, explain findings through design principles, and verify supported changes."
 ---
 # Cookbook: review a UI design
 English | [中文](reviewing-ui-design.zh.md)
 ## Summary
 Use this workflow for impact-scoped UI changes and explicitly requested whole-interface reviews. Read the page or modal as context, compare affected relationships across and within groups, then record findings and make authorized changes. The [principles and case reference](../ui-design-review-cases.md) supplies judgment criteria; examples do not define coverage. The [required review loop](../../.agents/skills/dsh-client-ui-ux/SKILL.md#required-review-loop) owns triggers, execution timing and completion criteria.
 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).
 For sidebar review, record the current master revision and follow the [sidebar design baseline](../../.agents/skills/dsh-ui-alignment/SKILL.md#sidebar-design-baseline). Capture its relevant roles and states before comparing the working version. Older illustrations and reports cannot establish the current layout or justify restoring superseded geometry.
 ## Table of Contents
 - [1. Define the page or modal in scope](#proposition)
 - [2. Inspect the task and its implementation](#inspect)
 - [3. Preserve the starting point](#baseline)
 - [4. Change the smallest responsible component](#implement)
 - [5. Verify behavior and comparable images](#verify)
 - [6. Deliver the complete evidence](#deliver)
 - [Further Exploration](#further-exploration)
 - [Dev Note](#dev-note)
 <a id="proposition"></a>
 ## 1. Define the page or modal in scope
 Name the user task and affected page or modal. Select the scope below before editing; routine changes do not default to a product-wide audit. For an explicit full review, enumerate the pages and modals and inspect every region and relevant state within that scope. State local scope and do not present its result as a whole-page conclusion.
 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.
 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.
 <a id="review-scope"></a>
 ### Select scope by visual impact
 Record the scope in a few task-note sentences before editing: changed position → affected groups and shared axes → consumers and conditions → planned evidence. Use a table only when several pages or variants need tracking. File count and package boundaries do not determine visual reach.
 | Change | Minimum inspection scope |
 |---|---|
 | Local copy, icon, color or spacing | Read the containing page or modal for context; inspect the owning group, neighboring groups and affected peers sharing its axes or role, including distant peers |
 | Page, form or card layout; new page or modal | Review the containing page or modal as a whole, including relevant scrolling and expanded content |
 | Shared component | Trace all affected consumers; inspect each distinct layout, content and state variant in its assembled context |
 | Global typography, tokens or styling | Map affected component families and page layouts; expand coverage across those families, rather than treating the change as local |
 | Behavior without an intended style change | Inspect the states that can change visible relationships, including loading, errors, disabled controls, expansion and focus |
 A shared consumer can reuse evidence only when the relevant implementation, size, container constraints, content behavior and states are equivalent; record the grouping and its basis. Inspect uncertain cases directly. Source inspection of all consumers is not a claim to have opened every page. Expand scope when a defect recurs beyond the initial region or a fix changes adjacent relationships. Record unrelated discoveries separately instead of silently starting a product-wide redesign.
 Choose conditions that challenge the change: long or multiline content for sizing, both themes for color, constrained widths and affected breakpoints for layout, and concurrent states for interaction. Apply the owning responsive and behavior requirements; do not exhaust unrelated combinations or replace coverage reasoning with a fixed screenshot count. Reuse unchanged rules and valid evidence within the task, and recapture after a coherent batch of edits rather than every CSS adjustment. Read only the relevant principle sections and examples; an uncertain design decision is a reason to retrieve more detail.
 <a id="inspect"></a>
 ## 2. Inspect the task and its implementation
 Open the actual application at the task's normal entry point. Read in the user's order: page purpose, current content or selection, relevant explanation, primary action, then secondary actions. Identify where alignment, spacing, emphasis, or a control's behavior contradicts that order. Inspect the owning component and its computed styles to distinguish a real layout defect from content, loading, or an unfinished animation.
 Write each candidate as a short finding: scene and state, observable effect on the task, source owner, smallest proposed change, and the condition that would make the change inappropriate. Prioritize frequent or shared controls and clearly visible defects. A source search for differing numbers is evidence to inspect, not sufficient reason to standardize them.
 ### 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.
 Apply the [whole-page and modal principles](../ui-design-review-cases.md#whole-interface-review) to the selected scope. Keep the whole composition as context and compare affected regions and repeated relationships before using local fixtures for detail. Explicit full reviews cover every region; local corrections must preserve neighboring alignment, grouping, nested corners, clipping and focus.
 ### Make the relationships explicit
 Before reading CSS, name the semantic groups and draw their shared axes on a full-context screenshot or a simple diagram. Include repeated elements across component boundaries. Record the following for each region; these are review notes, not a new product configuration file.
 | Observation | Record | Example |
 |---|---|---|
 | Task and groups | What each group describes or operates on; its children and neighboring groups | Conversation title / three-action cluster; members section / tasks section |
 | Alignment | Objects, axis, and reference container; deliberate exceptions | Baseline-defined peer-row text starts; centered icon-plus-label in the primary button |
 | Spacing | Which gaps are internal, repeated, and between groups | Heading is closer to its cards than to the preceding section |
 | Peer geometry | Comparable roles and visible size, radius, and color relationships | Equal circular bases; one search-prompt foreground role |
 | States | Simultaneous and neighboring combinations | Selected conversation beside another hovered conversation |
 | Evidence scope | What is visible and what remains uninspected | Full Desktop sidebar versus an isolated conversation row |
 Walk the region in three passes: whole composition, relationships between groups, and details within groups. Use source and computed geometry to explain the visible result afterward. For alignment, compare rendered text starts and slot centers; for spacing, compare visible boundaries as well as CSS boxes. Record CSS pixels separately from screenshot pixels and preserve the zoom/device scale. Do not infer a new design constant from a scaled image.
 A useful finding states a violated relationship: “The title-to-action gap is smaller than the gaps inside the action cluster, so the title joins the first action visually; separate the two groups and retest long-title hover.” “Spacing looks off” and “all gaps use tokens” do not explain the judgment. A visible inconsistency can fail the design requirement even when it does not block a task; do not dismiss it as harmless because a click still succeeds.
 Before declaring the page or modal reviewed, reconcile its actual regions and relevant states with the inspected evidence. Include content reached by scrolling, expansion or tab changes. A local fixture or example cannot substitute for an uninspected part of that whole. For a limited review, list the remaining scope explicitly.
 Use locally maintained production-component fixtures to reproduce controlled states or compare variants. They supplement actual application inspection. Capture/report tools and their scene adapters can live outside the repository and consume the source checkout; they are not required product dependencies or CI acceptance. Read their local instructions for supported scenes and limits.
 ### Keep a coverage record
 Use the following record for multi-region reviews; a local change can keep the same facts in a short task note. Do not target a fixed case count. Inspect the selected pages, groups and relationship-changing expansions in context; associate shared-component changes with their affected consumers and any justified equivalent groups.
 | Page or dialog and entry | Semantic groups and cross-group relationships | Inspected conditions | Finding and owner | Evidence after correction | Uninspected |
 |---|---|---|---|---|---|
 | Name the actual entry and region | Specify both endpoints and complete boxes or text axes | Content, width, theme, state | Record the rule and responsible component | Comparison and relevant behavior results | State limits rather than an ambiguous covered status |
 Write each finding as observation, compared objects and intended relationship, structural or computed-style evidence, smallest responsible correction, neighboring relationships at risk, and recheck conditions. Keep insufficiently supported candidates pending instead of applying bulk changes; trace confirmed problem classes through actual consumers until repeated occurrences within the declared scope have recorded results.
 <a id="baseline"></a>
 ## 3. Preserve the starting point
 Record the starting source and capture the relevant scenes before editing. Existing uncommitted work is part of that starting point: preserve it with a recoverable snapshot or exact file copies, and compare this round against that snapshot rather than assuming `HEAD` represents the visible application. Keep the source version, scene inputs, and capture conditions with the evidence.
 Save the baseline captures with their source identity and conditions in a local evidence directory.
 Map every intended visible change to a scene before implementing it. Include controls inside expanded rows, dialogs, alternate provider forms, and loading or disabled states when those positions change. One screenshot of a collapsed parent does not cover its hidden controls. Use safe fixture data for destructive or unavailable states instead of saving changes to a user's real task solely to obtain a screenshot.
 <a id="implement"></a>
 ## 4. Change the smallest responsible component
 Fix the owner that creates the inconsistency. A page layout belongs to that page; a shared control state belongs to its primitive; a glyph’s optical viewport belongs to the icon library when the imbalance follows it across consumers. Reuse existing components and theme aliases. Keep each correction tied to a finding from the whole-interface review, recheck affected relationships, and preserve independent workspace changes.
 Check the states that can conflict with the change: for example selected with hover or keyboard focus, expanded with focus, busy with disabled, and validation with long content. Check the narrow container and the width just on each side of a changed breakpoint. Preserve input drafts, keyboard focus, dismissal, and access to the primary action when layout changes. Follow the [testing policy](../testing.md) for checks that exercise behavior; do not add assertions that merely repeat CSS declarations.
 Verify the causal structure first, confirm that styles actually apply, then inspect appearance and behavior. Record complete icon boxes, text starts, painted button edges, and hit-target positions separately where useful; target rectangles cannot stand in for every alignment measurement. Shared-component adjustments include consumers with and without optional descriptions, unequal content, and real neighbors rather than only the report fixture.
 When build or hot-reload state is uncertain, create a separate application instance using the intended sources and verify its artifacts to avoid old scripts with new styles. An unchanged DOM snapshot, stale test selector, or failing capture hook cannot establish whether a visual correction passes or fails; identify the failure owner and verify current behavior with relevant tests without capture hooks.
 <a id="verify"></a>
 ## 5. Verify behavior and comparable images
 Verify the result in the actual application where reachable. Supplement it with production-component fixtures for precise or hard-to-reach states, clearly labeling that source. Use the same content, theme, locale, viewport, zoom, device scale, interaction state, and content anchor for each comparison. Let fonts, data, and transitions settle; a static capture mode may suppress motion in the fixture, but must retain the intended final state.
 Save final captures in a separate directory and pair them by scene identity and matching conditions.
 Check matching capture IDs, dimensions and conditions against the declared scene inventory. Resolve mismatches by correcting the scene or capture conditions. Do not stretch an image, silently change its crop, or present a reconstructed fixture as an earlier application screenshot. A comparison report proves neither complete change coverage nor visual quality: reconcile the expected scenes with the final changes and inspect every image yourself.
 Two captures with the same rendered-source fingerprint demonstrate the capture and reporting workflow, not a UI improvement. An actual before-and-after comparison captures the starting implementation before editing and the resulting implementation afterward. Keep that distinction visible in the delivered report.
 Use equal-sized paired crops with the same content origin when a full page hides a small difference; retain enough context to show the relationship being judged. If a content change requires a different crop, disclose it and keep the original full-context captures available. Verify both themes when color, state, or icon balance is involved, and use enlarged views only as a supplement to the intended display size.
 <a id="deliver"></a>
 ## 6. Deliver the complete evidence
 Present each case as scene and problem, design judgment, then its screenshot or paired comparison immediately below. Add a caption naming what to inspect, what each side means, and the source. Do not collect unrelated cases into a detached screenshot wall. If the difference is only faintly visible or the image omits the relationship, choose stronger evidence instead of presenting it as a design exemplar.
 Present each proposition with a concise explanation and its before-and-after pairs, before on the left and after on the right, linked to the originals. Identify actual application captures and isolated production-component scenes separately. If the user requests all changes, reconcile the final diff against the scene map and cover every changed visible position, including nested controls; state any missing evidence explicitly.
 For each reviewed region, report one of: no visible defect found in the stated conditions, a defect with evidence, or not inspected. A finding includes the compared objects, applicable rule owner, intended relation, visible difference, correction, plausible wrong fix, retest condition, and any justified exception. Do not average away a known alignment/grouping failure with unrelated passing checks or infer an overall pass from representative glyphs.
 Report the checks actually run and their outcome, and distinguish automated metadata checks, behavior tests, and human visual inspection. Include material limitations such as an unavailable application state or an untested platform. Do not describe the work as fully verified while required scenes or checks remain outstanding.
 Before handoff, apply the [completion criteria](../../.agents/skills/dsh-client-ui-ux/SKILL.md#required-review-loop) to the final diff and retained evidence. A concise result with scope, comparison and relevant checks suffices for a local change; a large report is not required. Before PR or push, check cumulative interactions and evidence validity, and rerun only invalidated or missing checks. This is an agent review obligation, not automatic visual approval by CI. Human review for consequential design decisions follows the [escalation rule](../../.agents/skills/dsh-client-ui-ux/SKILL.md#design-review-escalation); explicitly requested or periodic human audits supplement daily checks.
 ### Comparison delivery and cumulative changes
 Keep before on the left and after on the right; use horizontal browsing on narrow screens rather than splitting a pair vertically. Mark regions with a few boxes, shared axes with dashed lines, and locations with arrows only on the after side; annotations must not obscure the text or icons under inspection. Keep annotations as a removable overlay and retain untouched original captures. Explain the relationship before its comparison; retain both endpoints for cross-group findings, supplementing with detail crops and complete pages when needed. Recheck a general report tool’s default presentation against this section; successful generation does not establish left/right layout or after-side annotation compliance.
 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.
 <a id="further-exploration"></a>
 ## Further Exploration
 Use these owners for the details needed by a particular review.
 - [UI design principles and review cases](../ui-design-review-cases.md) — whole-page and modal judgment, applicable rules, and explanatory examples.
 - [Rule ownership and maintenance](../../.agents/skills/dsh-client-ui-ux/SKILL.md#maintain-one-owner-per-rule) — where to change a principle and how local tools consume it.
 - [Web UI style reference](../web-styling.md) — component reuse and styling ownership.
 <a id="dev-note"></a>
 ## Dev Note
 None.
@@ -0,0 +1,162 @@
 ---
 description: "把 DSH 页面或弹窗作为整体审查，按设计原则说明问题，并验证有依据的修改。"
 ---
 # Cookbook：审查 UI 设计
 [English](reviewing-ui-design.md) | 中文
 ## 概览
 本流程用于按影响范围审查 UI 改动，以及用户明确要求的完整界面审查。先以页面或弹窗为上下文，比较受影响的组间与组内关系，再记录发现并执行已授权的修改。[原则与案例参考](../ui-design-review-cases.zh.md)提供判断依据，例子不定义覆盖范围。[必需审查流程](../../.agents/skills/dsh-client-ui-ux/SKILL.md#required-review-loop)统一规定触发条件、执行时机和完成标准。
 对齐审查先核对图标完整空间（含有意保留的内部留白）、文字列和间距，再检查实际轮廓。热区不等于图标框；不逐个拉齐 glyph 的像素边缘。判断顺序见[对齐原则](../ui-design-review-cases.zh.md#alignment)。
 侧栏审查记录当前 master 版本，并遵循[侧栏设计基线](../../.agents/skills/dsh-ui-alignment/SKILL.md#sidebar-design-baseline)。先保留相关角色与状态的基线，再比较工作版本。旧示意图和报告不能证明当前布局，也不能作为恢复已被取代的几何关系的理由。
 ## 目录
 - [1. 确定受审页面或弹窗](#proposition)
 - [2. 检查任务路径与实现](#inspect)
 - [3. 保留起点](#baseline)
 - [4. 修改最小责任组件](#implement)
 - [5. 验证行为与可比较的截图](#verify)
 - [6. 交付完整证据](#deliver)
 - [延伸阅读](#further-exploration)
 - [开发备注](#dev-note)
 <a id="proposition"></a>
 ## 1. 确定受审页面或弹窗
 写明用户任务和受影响的页面或弹窗，编辑前按下文选择范围；日常改动不默认扩大为整个产品审查。明确要求完整审查时，列出页面与弹窗，检查范围内所有区域及相关状态。局部审查要说明范围，不将结果表述为整页结论。
 在这个范围内应用[判断优先级](../ui-design-review-cases.zh.md#judgment)：先检查对齐与空间分组，再审查密度、层级、状态、组件选型、图标光学和几何。每个发现写成可观察的关系，例如内容与隔壁组的距离反而小于与自身标签的距离。遵循用户指定的顺序和授权；完整审查可以发现多个相关问题，已有实施授权不需要为常规调整重复请求批准。
 编辑前阅读[客户端 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)。本流程补充审查和证据步骤，不另建一套视觉令牌。
 <a id="review-scope"></a>
 ### 按视觉影响选择范围
 编辑前用几句话记录：改动位置 → 受影响的组与共用轴线 → 使用方及条件 → 计划保留的证据。涉及多个页面或变体时再用表格追踪。文件数量和包边界不能决定视觉影响范围。
 | 改动 | 最小检查范围 |
 |---|---|
 | 局部文案、图标、颜色或间距 | 先看所属页面或弹窗的上下文；检查所属组、相邻组及共用轴线或角色的受影响并列元素，包括远处的并列元素 |
 | 页面、表单或卡片布局；新页面或弹窗 | 将所属页面或弹窗作为整体审查，包含相关滚动和展开内容 |
 | 共享组件 | 排查全部受影响使用方；在实际组合上下文中检查每种不同的布局、内容和状态变体 |
 | 全局字体、令牌或样式 | 梳理受影响的组件族与页面布局，按这些类别扩大覆盖，不能当成局部改动 |
 | 没有预期样式变化的行为改动 | 检查可能改变可见关系的状态，包括加载、错误、禁用、展开和焦点 |
 只有相关实现、尺寸、容器约束、内容行为和状态等价时，共享组件使用方才能复用证据；记录归类和依据。不确定的场景直接检查。源码排查全部使用方不等于逐页打开过。问题在初始区域外重复出现，或改法影响邻接关系时，扩大范围。无关发现单独记录，不静默开始整个产品重设计。
 按改动选择挑战条件：尺寸检查长文案或多行内容，颜色检查明暗主题，布局检查窄容器和受影响断点，交互检查共存状态。遵守所属响应式与行为要求，不穷举无关组合，也不用固定截图数替代覆盖判断。同一任务中复用未变规则和有效证据，一组相关修改完成后再截图，不逐条 CSS 调整都重拍。只读取相关原则和案例；设计判断不明确时再补充查阅。
 <a id="inspect"></a>
 ## 2. 检查任务路径与实现
 从正常入口打开实际应用。按用户的顺序阅读：页面用途、当前内容或选择、相关说明、主操作，再到次要操作。找出对齐、间距、强调方式或控件行为与该顺序冲突的位置。检查所属组件及其计算样式，区分真实布局缺陷与内容、加载或尚未结束的动画造成的现象。
 将候选问题写成简短发现：场景与状态、对任务可见的影响、源码归属、最小建议改法，以及不适用该改法的条件。优先高频或共享控件和明显缺陷。搜索到源码中的数值差异，只能说明需要检查，不能直接成为统一数值的理由。
 ### 在整个界面内核对适用规范
 按[适用规范映射](../ui-design-review-cases.zh.md#review-baseline)收集本任务相关的当前圆角、材质、字体、组件、反馈、响应式和图案规则，记录明确例外与相关已有变体。个人或外部 skill 不同时，以仓库所有方为准；实现与所有方不同时，把差异保留为发现，不能默默任选一方。
 将[整页与整个弹窗的审查原则](../ui-design-review-cases.zh.md#whole-interface-review)应用于选定范围。保留整体构图上下文，先比较受影响区域与重复关系，再用局部 fixture 分析细节。明确的完整审查覆盖全部区域；局部修正需保留邻接的对齐、分组、嵌套圆角、裁切与焦点关系。
 ### 把关系明确写出来
 阅读 CSS 前，先说清语义组，并在保留上下文的截图或简图上画出共用轴线，包含跨组件的重复元素。为每个区域记录以下内容；这些是审查笔记，不是新的产品配置文件。
 | 观察项 | 记录内容 | 示例 |
 |---|---|---|
 | 任务与分组 | 每组描述或操作什么，包含哪些子组，与谁相邻 | 会话标题／三操作组；成员区／任务区 |
 | 对齐 | 对象、轴线、参照容器及有意的例外 | 基线定义的同类行文字起点；主按钮内 icon＋文字整体居中 |
 | 间距 | 哪些是组内、重复单元之间和组间距离 | 标题与所属卡片比与前一个分区更近 |
 | 并列几何 | 可比较角色的可见尺寸、圆角与颜色关系 | 圆形底板等大；搜索提示共用一个前景色角色 |
 | 状态 | 同时叠加及相邻共存的组合 | 当前会话选中，同时另一条会话悬停 |
 | 证据范围 | 能看到什么，哪些尚未检查 | 完整 Desktop 侧栏与隔离会话行的区别 |
 按整体构图、组与组的关系、组内细节三层观察，再用源码与计算几何解释可见结果。对齐比较实际文字起点和槽位中心；间距同时比较可见边界与 CSS 框。区分 CSS 像素与截图像素，保留缩放和设备像素比，不从缩放后的图片推导新的设计常数。
 有效发现要说明违反了什么关系：“标题到操作组的距离小于操作组内部距离，视觉上把标题粘到首个操作；分开两组，并重测长标题悬停。”只说“间距不对”或“都使用 token”都没有完成判断。明显不一致即使不阻塞任务，也能构成设计不通过，不能因为仍然点得动就忽略。
 宣布页面或弹窗审查完成前，将它实际包含的区域和相关状态与已检查证据逐一核对，包含滚动、展开或切换标签页后才能看到的内容。局部 fixture 或案例不能替代这个整体中尚未检查的部分。局部审查则明确列出未覆盖范围。
 用本地维护的生产组件 fixture 复现受控状态或比较变体，作为真实应用检查的补充。截图、报告工具及其场景适配可放在仓库外并读取源码工作树，不作为产品依赖或 CI 验收；支持场景与限制以工具的本地说明为准。
 ### 为审查建立覆盖记录
 多区域审查使用下列记录；局部改动可用简短任务笔记记录相同事实。不把固定案例数量当作目标。在上下文中检查选定页面、分组与改变关系的展开区，关联共享组件的受影响使用方及有依据的等价分组。
 | 页面／弹窗与入口 | 语义组及跨组关系 | 已查条件 | 发现与归属方 | 修正后证据 | 尚未检查 |
 |---|---|---|---|---|---|
 | 填实际入口与区域 | 指定比较两端、完整框或文字轴 | 内容、宽度、主题、状态 | 记录规则和责任组件 | 对照图与相关行为结果 | 写明限制，不留含糊的“已覆盖” |
 每个发现按“现象 → 比较对象与预期关系 → 结构或计算样式证据 → 最小责任改法 → 可能破坏的邻接关系 → 复查条件”书写。证据不足的候选保留为待核实，不先批量修改；已确认的同类问题则沿实际使用方继续查找，直到本次声明范围内的重复位置均有结果。
 <a id="baseline"></a>
 ## 3. 保留起点
 编辑前记录起始源码并拍摄相关场景。已有未提交改动也是起点的一部分：用可恢复快照或精确文件副本保留它，并以该快照比较本轮变化，不能假定 `HEAD` 就是当前可见应用。证据同时保留源码版本、场景输入和截图条件。
 把基线截图及其源码身份、截图条件保存在本地证据目录。
 实施前，为每处计划中的可见修改对应一个场景。展开行、对话框、不同提供商表单，以及加载或禁用状态中的位置发生变化时，也要纳入。折叠父组件的一张截图不能覆盖隐藏控件。破坏性或暂不可达的状态使用安全 fixture 数据，不要仅为截图而保存对用户真实任务的修改。
 <a id="implement"></a>
 ## 4. 修改最小责任组件
 修改产生不一致的归属方。页面布局由该页面负责，共享控件状态由基础组件负责；若一个 glyph 在多个使用位置都失衡，则由图标库负责它的光学视口。复用现有组件和主题别名。每处修正对应整体审查中的一个发现，复查受到影响的关系，并保留工作区已有的独立改动。
 检查可能与本次修改冲突的状态，例如选中与悬停或键盘焦点叠加、展开与焦点叠加、忙碌与禁用叠加，以及校验信息与长内容共存。检查窄容器和变更断点两侧的临界宽度。布局变化时保留输入草稿、键盘焦点、关闭方式及主操作的可达性。按[测试策略](../testing.zh.md)验证行为，不添加只复述 CSS 声明的断言。
 先验证造成问题的结构，再确认样式实际生效，最后检查视觉与行为。可记录完整 icon 框、文字起点、按钮可见边缘和热区各自的计算位置；不要拿热区矩形代替全部对齐证据。公共组件的调整至少覆盖有／无可选说明、长短内容与实际相邻控件，不能仅修复报告中的一个 fixture。
 构建或热更新状态不确定时，重新建立使用目标源码的独立应用实例并核对产物，避免旧脚本配上新样式。仅因 DOM 快照没变、测试选择器过期或截图钩子失败，不能判定视觉修正通过或失败；定位失败归属，再以更新后的真实行为预期和无截图钩子的相关用例验证。
 <a id="verify"></a>
 ## 5. 验证行为与可比较的截图
 能够到达时，在实际应用中验证结果。精确或难以到达的状态可补充生产组件 fixture，并明确标注来源。每组对照保持相同内容、主题、语言、视口、缩放、设备像素比、交互状态和内容锚点。等待字体、数据和过渡稳定；fixture 的静态截图模式可以停用动画，但必须保留预期终态。
 把最终截图保存到独立目录，并按场景身份及相同条件配对。
 按声明的场景清单检查两侧截图 ID、尺寸和条件是否一致。条件不符时修正场景或截图条件。不要拉伸图像、默默改变裁剪范围，或把重建 fixture 当作更早的应用截图。对比报告不能证明改动覆盖完整，也不能证明视觉质量；仍需将预期场景与最终改动核对，并亲自检查每张图。
 两次截图的渲染源码指纹相同时，只能演示截图与报告流程，不能证明 UI 改进。真正的前后对照应当在编辑前拍摄起始实现，编辑后拍摄结果实现。交付报告中也要清楚保留这一区别。
 整页截图掩盖细小差异时，可使用尺寸相同、内容起点相同的成对裁剪图，并保留足以判断关系的上下文。内容变化确实需要不同裁剪时，说明差异，并保留完整上下文的原图。涉及颜色、状态或图标平衡时验证明暗两种主题；放大图只能补充实际显示尺寸下的检查。
 <a id="deliver"></a>
 ## 6. 交付完整证据
 每个案例按“场景与问题 → 设计判断 → 紧接下方的截图或成对对照”呈现。图注说明看哪里、两侧分别表示什么及来源。不要把无关案例集中成脱离正文的截图墙。差异只有勉强可辨、或图片没有包含所讨论关系时，应选择更有解释力的证据，不能将其当作设计范例。
 每个命题附简短说明与前后对照，左侧为修改前，右侧为修改后，并链接原图。分别标明实际应用截图与生产组件隔离场景。用户要求全部修改时，将最终 diff 与场景映射逐项核对，覆盖每个发生变化的可见位置，包括嵌套控件；缺少的证据明确说明。
 每个受审区域分别报告：在所述条件下未发现可见缺陷、有证据的缺陷、或尚未检查。发现包含比较对象、适用规则所有方、预期关系、可见差异、修正、看似合理的误修、复查条件及合理例外。不能用无关检查通过来抵消已知的对齐／分组失败，也不能由代表 glyph 推断整体通过。
 报告实际运行的检查及结果，区分自动元数据校验、行为测试与人工读图。说明重要限制，例如应用状态暂不可达或某个平台尚未测试。必需场景或检查未完成时，不要声称已经完整验证。
 交付前，按[完成标准](../../.agents/skills/dsh-client-ui-ux/SKILL.md#required-review-loop)核对最终 diff 与保留证据。局部改动提供简短范围、对照和相关检查结果即可，不要求大型报告。推 PR 或推送前检查累计影响与证据有效性，只补做失效或缺失的检查。这是 agent 的执行要求，不代表 CI 自动批准视觉质量。重要设计决策按[人工审查条件](../../.agents/skills/dsh-client-ui-ux/SKILL.md#design-review-escalation)处理；明确要求或定期开展的人工审查补充日常检查。
 ### 对比交付与累计改动
 对照固定为左前右后；窄屏保持成对横向浏览，不自动拆成上下两张。右图用少量框标区域、虚线标共同轴、箭头指位置；标注不能遮住待检查的文字或图标。标注作为可关闭的叠加层，保留未修改的原始截图。每个案例先解释关系，再紧接对照；涉及跨组关系时保留两端，必要时另附局部放大和完整页面。 通用报告工具的默认排版仍需按本节复查；生成成功不表示已经满足左右布局和右图标注要求。
 累计汇总按位置去重：在条件可比的前提下，将最早可靠的修改前截图与最终实现配对。中间轮次只保留为历史证据，不作为独立最终成果；撤销方案不计入现存成果。另一会话的保留改动单列，不归为本次成果。缺少起点或归属不确定时明确说明。记录实际检查，不将重复执行数量当作新增覆盖。
 <a id="further-exploration"></a>
 ## 延伸阅读
 按本次审查需要查阅对应归属文档。
 - [UI 设计原则与审查案例](../ui-design-review-cases.zh.md)——整页与整个弹窗的判断原则、适用规则及解释性案例。
 - [规则归属与维护](../../.agents/skills/dsh-client-ui-ux/SKILL.md#maintain-one-owner-per-rule)——原则的修改位置及本地工具的读取方式。
 - [Web UI 样式参考](../web-styling.zh.md)——组件复用与样式归属。
 <a id="dev-note"></a>
 ## 开发备注
 无。
@@ -0,0 +1,139 @@
 # Bilingual-pair consistency record for ui-design-review-cases.md (docs/i18n/README.md): per heading
 # section, a hash of its English and Chinese blocks outside code blocks and generated regions.
 # After editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/ui-design-review-cases.md
 /:
  en: 1da13fa1c536aa24
  zh: 52ef6218c8cea359
 /ui-design-principles-and-review-cases:
  en: 4be954bceeeb7940
  zh: d91f6595cd3e85f0
 /ui-design-principles-and-review-cases/summary:
  en: 1f22942d484be109
  zh: 0b0ac297328aa0f2
 /ui-design-principles-and-review-cases/table-of-contents:
  en: 683b785991a7952d
  zh: e0a9f88db5cf9c45
 /ui-design-principles-and-review-cases/what-a-review-must-judge:
  en: e51c9f121c18c998
  zh: 93b35a247216be09
 /ui-design-principles-and-review-cases/review-the-entire-page-or-modal-as-one-unit:
  en: 324c8d9a0ff36ebb
  zh: 3a4c64e15b59f98f
 /ui-design-principles-and-review-cases/review-the-entire-page-or-modal-as-one-unit/judge-the-whole-the-groups-and-the-elements:
  en: 08450af012ed9ae9
  zh: 7776aad3791eee79
 /ui-design-principles-and-review-cases/review-the-entire-page-or-modal-as-one-unit/relate-each-finding-back-to-the-whole:
  en: 40b5b26e5ff31ae8
  zh: 0fdb1fdef7243c35
 /ui-design-principles-and-review-cases/review-the-entire-page-or-modal-as-one-unit/use-a-relationship-inventory-to-establish-coverage:
  en: 138392750105bf23
  zh: 2cf34065251d93df
 /ui-design-principles-and-review-cases/combine-the-applicable-standards-first:
  en: fd2d0f3433eb7e20
  zh: 2034723f45360e79
 /ui-design-principles-and-review-cases/choose-cases-that-expose-a-design-decision:
  en: f8b0f72251aa044f
  zh: a8b05ce5f3da4221
 /ui-design-principles-and-review-cases/principle-examples:
  en: 1ff7bb879b274363
  zh: 4659578bcdea82a3
 /ui-design-principles-and-review-cases/1-alignment:
  en: 7f814736464f0d76
  zh: f2aad824c15a6ca3
 /ui-design-principles-and-review-cases/1-alignment/text-metrics-and-unequal-content:
  en: 14558eb00e9b4902
  zh: 333b28dabfccbd6c
 /ui-design-principles-and-review-cases/1-alignment/example-a1-role-based-sidebar-alignment:
  en: 7eaa16a7415823b0
  zh: d0cbb3a4144c7948
 /ui-design-principles-and-review-cases/1-alignment/example-a2-distinct-header-and-row-action-groups:
  en: 5067e586053db8d5
  zh: 153168b1016950d1
 /ui-design-principles-and-review-cases/1-alignment/example-a3-alignment-between-rows-and-compound-controls:
  en: 0f387b953c8c3e34
  zh: 5362d3467a65ec59
 /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
 /ui-design-principles-and-review-cases/2-spatial-grouping:
  en: f50b8851f4ee2ac3
  zh: 63076543756c294e
 /ui-design-principles-and-review-cases/2-spatial-grouping/example-g1-separating-content-from-its-action-group:
  en: a4c0b1f1ad441155
  zh: 360ed71994a101a8
 /ui-design-principles-and-review-cases/2-spatial-grouping/example-g2-spacing-between-complex-sections:
  en: 2585b4f2a35bda67
  zh: 59b6c9d987ee95bb
 /ui-design-principles-and-review-cases/2-spatial-grouping/example-g3-nested-groups-along-the-reading-order:
  en: 4d24915951f86d97
  zh: 4d6c348fdb7b78de
 /ui-design-principles-and-review-cases/2-spatial-grouping/example-g3-nested-groups-along-the-reading-order/primer-equal-control-widths-do-not-fix-a-broken-reading-order:
  en: 65f62d6b2d933d6e
  zh: 3332fa1c82053c71
 /ui-design-principles-and-review-cases/2-spatial-grouping/example-g3-nested-groups-along-the-reading-order/carbon-different-distances-carry-different-meanings:
  en: 9d7e04a0314ac527
  zh: fc654332df43d0c1
 /ui-design-principles-and-review-cases/2-spatial-grouping/example-g4-separating-groups-with-different-purposes:
  en: 0e4b070c7bd088a1
  zh: 736b5978d42a7c55
 /ui-design-principles-and-review-cases/2-spatial-grouping/composed-whitespace-and-responsive-grouping:
  en: 47f8ea920c78c5be
  zh: e64ab054666c3727
 /ui-design-principles-and-review-cases/3-whole-page-density:
  en: 10fb29eddaac1951
  zh: e05636b47e860966
 /ui-design-principles-and-review-cases/4-information-hierarchy:
  en: 7defd0a4ca8d2c07
  zh: 7911c63ad109aeb9
 /ui-design-principles-and-review-cases/4-information-hierarchy/example-c1-color-emphasis-within-one-information-unit:
  en: ae07e8886d00c5bb
  zh: 1229ab4ae6394c0b
 /ui-design-principles-and-review-cases/5-control-states:
  en: d247699132b484a0
  zh: b71e25d834ce2633
 /ui-design-principles-and-review-cases/5-control-states/example-s1-persistent-selection-beside-temporary-hover:
  en: e6c650517a1e938c
  zh: 0aa7f8f2e8bd22c3
 /ui-design-principles-and-review-cases/6-component-choice:
  en: 7a49fdd5a601aa48
  zh: e2f9de0d5628a878
 /ui-design-principles-and-review-cases/7-icon-optics:
  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
 /ui-design-principles-and-review-cases/8-control-geometry-and-corner-relationships:
  en: 262cfa8e7dfb969f
  zh: 4987ad06db795885
 /ui-design-principles-and-review-cases/8-control-geometry-and-corner-relationships/decide-geometry-in-this-order:
  en: 26419c2cbae93712
  zh: 0f72032f89169b75
 /ui-design-principles-and-review-cases/8-control-geometry-and-corner-relationships/decide-geometry-in-this-order/fluent-the-split-button-notch-is-a-relationship-error:
  en: ac1410636b2683ae
  zh: c39f006a594cbc36
 /ui-design-principles-and-review-cases/8-control-geometry-and-corner-relationships/example-r1-radii-across-container-and-control-roles:
  en: d7833e6828c48bec
  zh: 66728e53ef3221dc
 /ui-design-principles-and-review-cases/8-control-geometry-and-corner-relationships/example-r2-small-selection-controls-within-a-form:
  en: e632805e838b1d3a
  zh: 6bda70ade710d4c0
 /ui-design-principles-and-review-cases/8-control-geometry-and-corner-relationships/example-r3-justified-geometry-differences-between-roles:
  en: 5137089b3644cfb5
  zh: e8b0da147f77a63e
 /ui-design-principles-and-review-cases/reproduce-and-compare:
  en: ec1ff65e6e15cea6
  zh: 9dc2344aadbbeea7
 /ui-design-principles-and-review-cases/external-references-and-what-dsh-adopts:
  en: 274dcca699c277ed
  zh: ecf31d4082bbd309
 /ui-design-principles-and-review-cases/external-references-and-what-dsh-adopts/codex-a-limited-reference-for-composition:
  en: 38e0bfd3e40da01d
  zh: 87aa406f9138be3e
 /ui-design-principles-and-review-cases/dev-note:
  en: b75c8458928b72b9
  zh: 003ba4e17b4b5269
@@ -0,0 +1,423 @@
 ---
 description: "Design judgment for DSH: alignment, spatial grouping, hierarchy, states, geometry, and worked review cases."
 ---
 # UI design principles and review cases
 English | [中文](ui-design-review-cases.zh.md)
 ## Summary
 Use this reference to review an entire page or modal as one visual unit. Judge alignment and spatial grouping across all regions, together with hierarchy, states, color, size and corner geometry. The examples illustrate transferable relationships; they do not define the set of screens to review. Images appear below their corresponding analysis. See the [review cookbook](cookbook/reviewing-ui-design.md) for the workflow and evidence requirements.
 ## 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)
 - [Principle examples](#case-index)
 - [1. Alignment](#alignment)
 - [2. Spatial grouping](#grouping)
 - [3. Whole-page density](#density)
 - [4. Information hierarchy](#hierarchy)
 - [5. Control states](#states)
 - [6. Component choice](#component-choice)
 - [7. Icon optics](#icon-optics)
 - [8. Control geometry and corner relationships](#geometry)
 - [Reproduce and compare](#reproduce)
 - [External references and what DSH adopts](#references)
 - [Dev Note](#dev-note)
 <a id="judgment"></a>
 ## What a review must judge
 A well-composed interface makes relationships visible before the reader studies individual labels. Alignment lets people compare parallel items without repeatedly searching for their starting points. Spacing tells them which icon, label, description, control, and action belong together. These are primary design requirements, including for a fully functional screen; they are not optional polishing after token checks pass.
 DSH prioritizes alignment and spatial grouping in visual review. First identify the task and semantic groups, then inspect shared axes across the whole region, then check each group's internal relationships. Follow with hierarchy, state, geometry, color, density, and optical detail. A blocked action or misleading state still takes priority over cosmetic work. Do not make every element equally large, equally spaced, or equally prominent in pursuit of consistency.
 The page or modal provides the reference for composition; the [impact scope](cookbook/reviewing-ui-design.md#review-scope) determines which relationships require inspection for a change. Navigation, content, forms and actions may come from different components while sharing text axes and spacing rules. Explain exceptions through role, hierarchy or state; component ownership alone is not a design reason.
 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.
 <a id="combined-cases"></a>
 <a id="whole-interface-review"></a>
 ## Review the entire page or modal as one unit
 Treat the entire page or modal as one visual unit when choosing references and judging relationships. A routine change reviews its affected groups and cross-group relationships in that context; it does not automatically audit every region or the whole product. An explicit whole-interface review must inspect all its regions. A sidebar, form or toolbar remains part of the larger composition even when owned by a separate component.
 For a modal, include its title, close control, all content sections, scrolling area and footer actions. For a page, include its navigation, header, toolbars, content and persistent actions. Content below the fold remains part of the same unit. Follow the page or modal's own edges when choosing alignment and centering references; an open modal has its own composition above the underlying page.
 ### Judge the whole, the groups and the elements
 First read the whole composition: content edges, visual center, reading order, primary action and overall density. Then identify groups and subgroups from what they describe or operate on. Compare neighboring groups, followed by the elements within them. Repeated relationships must remain consistent across the entire page or modal, including distant sections.
 | Aspect | Compare throughout the page or modal | Basis for judgment |
 |---|---|---|
 | Alignment | Text starts, icon centers, control edges, repeated action columns | Choose left, center or two-sided alignment by role; continue shared axes across groups; judge an icon and label together |
 | Spatial grouping | Label-to-content, item-to-item, group-to-group and section-to-section distances | Internal gaps are smaller than external gaps; more complex groups need greater separation; repeated group structures reuse internal gaps |
 | Size and proportion | Same-role controls, icon backgrounds, icons and adjacent text | Use consistent size variants and optical balance; adjusting size can support shared alignment |
 | Corner geometry | Containers, cards, fields, buttons and selection controls | Apply one role-based radius system throughout; distinguish inset, flush and independent relationships using the existing radius standard |
 | Color and emphasis | Text, associated icons, backgrounds, borders and secondary information | Match the emphasis of an icon and label that communicate together; explain role or state differences |
 | Typography and density | Headings, labels, descriptions, repeated rows and overall whitespace | Keep equal-level content consistent and make hierarchy readable; local spacing must fit the whole composition |
 | States and behavior | Selected, hovered, focused, disabled, expanded, loading and failed content | State changes preserve recognizable groups, alignment and action access; compare states that appear together |
 Consistency means applying the same reasoning throughout this unit. Elements with the same role and size variant follow the same treatment; differences follow from role, hierarchy or state. Being implemented by a different component does not justify a different text start, spacing pattern or radius. Likewise, a centered title and a left-aligned reading column can coexist when their roles support that composition.
 ### Relate each finding back to the whole
 Record which elements conflict, which relationship they should share, and how the correction fits the rest of the page or modal. Compare every occurrence of that relationship within the review scope. After a local adjustment, return to the whole composition and check affected axes, grouping, geometry and hierarchy together.
 A full review covers all regions in scope, including relevant scroll positions, expanded content and tabs, and states that change their relationships. Inspect supported widths, themes and input methods where applicable. Preserve drafts, focus, dismissal and primary-action access; show failures with the appropriate recovery. Report uninspected regions and states explicitly. One clean crop, component fixture or selected example cannot establish that the whole page or modal is consistent.
 ### Use a relationship inventory to establish coverage
 List the semantic groups in the assembled interface, then the relationships to compare: parent-child indentation, text columns across sections, repeated action slots, headings and descriptions, fields and validation, prose and inline controls, and scrolling content versus fixed actions. Inspect more than group interiors; every cross-group relationship needs two actually inspected endpoints. When changing a shared primitive, include consumers with and without descriptions, unequal content, and different action combinations.
 A relationship passes only when its structure uses one reference, its rendered appearance communicates that relationship, and relevant content or state changes preserve it. An existing assertion, shared token, successful capture, or isolated crop cannot replace these three requirements. Prioritize by misleading effect, frequency, and reach; a difference of only a few pixels does not excuse repeated misalignment.
 Record inspected without additional findings, fixed and rechecked, found but unresolved, and uninspected separately. Declare platform and exceptional-state limits where exhaustive coverage is unavailable; example counts, component-test counts, and page-entry counts do not establish that every design passes.
 <a id="review-baseline"></a>
 ## Combine the applicable standards first
 Use the [rule-owner map](../.agents/skills/dsh-client-ui-ux/SKILL.md#select-the-rule-owners) to select current implementation guidance, including alignment, spacing and icons.
 A review has two independent obligations: honor the applicable DSH rules and explain whether the assembled result communicates the intended relationships. A convincing silhouette does not excuse the wrong control semantics; legal tokens do not excuse bad alignment. For a scoped review, mark unrelated areas as out of scope. For a whole-interface review, apply the relevant rows below across all regions of the page or modal under review.
 | Owner | What it contributes to the review | What to compare across the page or modal |
 |---|---|---|
 | [Radius standard](ui-radius.md#radius-scale), [nested geometry](ui-radius.md#nested-hover) | Role before size; inset, flush-fill, and independent-child arrangements; curve and documented exceptions | Outer surface, field, hover fill, indicator and clipped edges together |
 | [Web styling](web-styling.md#component-rules) | Semantic colors, typography pairs, hairlines, elevation, menu material and motion | Same-role surfaces across features, both themes, native Desktop backdrop |
 | [Client UI/UX skill](../.agents/skills/dsh-client-ui-ux/SKILL.md) | Component reuse, hierarchy, loading, feedback ownership and window clearance | Loaded/empty/error scenes and the actual surrounding page |
 | [Responsive skill](../.agents/skills/dsh-responsive-ui/SKILL.md) | Space allocation before truncation, input capabilities, focus and primary-action access | Wide, constrained, keyboard and touch use of the same task |
 | [Official artwork skill](../.agents/skills/dsh-official-plugin-artwork/SKILL.md) | Package artwork semantics, optical balance, transparent regions and neighboring references | Plugin artwork in list and detail contexts; action icons remain a separate family |
 | [Error-handling skill](../.agents/skills/dsh-error-handling/SKILL.md#localized-actionable-visible-reports) | Visible failure, retained valid state and a safe next action | Field correction, failed operation and failed query as distinct situations |
 | [Primitives catalog](../packages/client/ui-primitives/README.md#component-catalog) and the relevant package README | Existing variants, focus/interaction behavior and feature-specific requirements | Intended component role versus a visually similar substitute |
 The current repository owner and its explicitly recorded exceptions take precedence over an older personal skill or external example. A user choice applies to its named family; it does not silently replace the global system. If implementation disagrees with its stated owner, report that discrepancy instead of treating the existing code as a new rule. Re-read the owner when selecting a radius or material rather than copying a scale into the review.
 <a id="case-selection"></a>
 ## Choose cases that expose a design decision
 An example makes a principle observable through a task, related elements, surrounding context and a condition that can challenge the correction. Extract the relationship and apply it throughout the page or modal being reviewed. A sidebar or model-editor example does not restrict that principle to those components. Examples are explanatory evidence, not a review menu or coverage list.
 Distinguish three kinds of evidence. An actual DSH scene establishes a defect in the displayed conditions. An official design-system example teaches a particular relationship; its dimensions and interaction policy remain that system's. An original diagram explains a proposed relation and must not be labeled an implemented improvement. A fixture only covers its rendered conditions. Keep source, compared objects, applied DSH rule and retest conditions adjacent to the case.
 Present each case as scene and problem, design judgment, then its screenshot or paired comparison immediately below. Add a caption naming what to inspect, what each side means, and the source. Do not collect unrelated cases into a detached screenshot wall. If the difference is only faintly visible or the image omits the relationship, choose stronger evidence instead of presenting it as a design exemplar.
 <a id="case-index"></a>
 ## Principle examples
 Use these examples to understand a relationship that is unclear. Apply the same principles to every relevant region of the current page or modal, including regions not illustrated here. Review scope comes from the requested interface, not from this example list.
 | Case | Relationship to inspect |
 |---|---|
 | [A1](#case-sidebar-axes) | Role-based sidebar alignment |
 | [A2](#case-action-columns) | Distinct header and row action groups |
 | [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 |
 | [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 |
 | [G4](#case-sidebar-groups) | Separating groups with different purposes |
 | [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 |
 | [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 |
 <a id="alignment"></a>
 ## 1. Alignment
 The [alignment skill](../.agents/skills/dsh-ui-alignment/SKILL.md) owns shared axes, complete layout boxes, indentation and text metrics. Use the examples below to apply those decisions.
 ![Alignment diagram: peer rows share axes while account and header controls retain their own geometry](assets/ui-design-review/principles-alignment.svg)
 The schematic distinguishes peer-row axes from account and header geometry; it is not a pixel specification. The [sidebar baseline](../.agents/skills/dsh-ui-alignment/SKILL.md#sidebar-design-baseline) owns current relationships. Compare content, painted backgrounds and hit targets separately; different roles need not share every axis.
 ### Text metrics and unequal content
 An inline icon refers to adjacent text, not the center of the entire paragraph line box. Cap height can calibrate a particular font combination, but is not a universal formula for every font and icon; do not copy one successful offset into every control. A status icon beside multiline guidance usually attaches to the first line, while a single-line button centers its icon and label together. Recheck that relationship after changes to font size, fallback, or language.
 The comparison below uses actual Markdown rendering, before on the left and after on the right, with annotations only on the right. CJK, Latin, and code links retain icon dimensions while font metrics correct vertical placement; external and internal gaps separately establish link grouping. Inspect wrapping in the complete paragraph for long links; this crop cannot establish their usability.
 ![Actual inline-link comparison: align icons with adjacent font metrics and retain internal whitespace](assets/ui-design-review/inline-metrics-comparison.png)
 Peer cards jointly establish heading starts, description first lines, and action edges. A short description must not independently center vertically because its neighbor is longer; place remaining height after the content group, while bottom actions may align separately. Equal card height does not establish a consistent reading order or require truncating real content to force equal heights.
 The comparison below shows actual preset cards with unequal descriptions. On the left, automatic margins detach the short description from its heading; on the right, descriptions start together below their headings and actions remain aligned. The relationship also applies to result cards, choice cards, and parallel summaries; it does not require every page to use cards.
 ![Actual peer-card comparison: align description first lines while retaining bottom action alignment](assets/ui-design-review/peer-content-comparison.png)
 <a id="case-sidebar-axes"></a>
 ### Example A1: Role-based sidebar alignment
 **Scene and relationship.** Compare navigation, workspace rows, conversations and the account area in the expanded sidebar against the recorded master baseline. Include the centered New conversation action and the painted row edges, not only text starts.
 **Failure and correction.** Applying one leading-slot width to every role can move titles, enlarge spacing or distort the signed-in account row. Preserve the owning shared variables, compact icon slots and paint insets. Retain deliberate account geometry and hierarchy instead of manufacturing one text axis across all roles.
 **Acceptance.** Mark guides only for relationships established by the baseline. Check short and long titles, optional icons, project expansion and signed-in/out account states. Revealing row actions must not move the title start. A list crop does not establish whole-sidebar alignment.
 <a id="case-action-columns"></a>
 ### Example A2: Distinct header and row action groups
 **Scene and relationship.** Workspace search/filter/add and conversation more/archive/pin occupy the trailing sidebar region but have different roles and spacing. Compare repeated rows with each other; compare the header with its own collapsed and expanded search states.
 **Failure and correction.** Forcing both groups into one three-slot grid changes the master design. Preserve each group's control sizes, gaps, trailing inset and search transition. Keep the title-to-action separation independent of the gaps inside a cluster.
 **Acceptance.** Show the header and row actions together, then expand search and collapse the sidebar. Verify the intended edge relationships, unclipped hit targets and long-title clearance. Do not add empty actions or offsets merely to make unrelated controls form vertical columns.
 <a id="case-preview-toolbar"></a>
 ### Example A3: Alignment between rows and compound controls
 **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.
 **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.
 <a id="case-empty-center"></a>
 ### Example A4: Centering a content group within its container
 **Scene and relationship.** The automation page has a heading and filters above an illustration, explanation, and create action. The empty-state group belongs in the available content region, with one shared horizontal center and a deliberate vertical position.
 **Failure and correction.** Horizontally centering each child while giving the parent fixed top padding leaves the whole group stranded near the top of a tall viewport. Let the content region occupy the remaining height, then position the complete group. Review its internal rhythm too; moving only the button does not center the group.
 **Acceptance.** Mark the remaining content rectangle and the bounds of the complete stack. Compare tall, short, and narrow windows with the same content. Distinguish a deliberate, documented optical offset from accidental fixed spacing; do not demand window centering when a sidebar or page toolbar changes the usable area.
 <a id="case-composer-controls"></a>
 ### Example A5: Visible size and center of peer controls
 **Scene and relationship.** Attachment and send actions anchor the same bottom toolbar. DSH's intended treatment uses equal circular bases and a shared vertical center; their different importance is expressed through fill and state.
 **Failure and correction.** Different base diameters plus an extra vertical translation create two unrelated anchors. Normalize the peer controls' outer geometry and remove layout compensation, then balance the plus and arrow within their slots. A thin plus and a solid arrow need not have equal painted area.
 **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.
 <a id="grouping"></a>
 ## 2. Spatial grouping
 The [spacing skill](../.agents/skills/dsh-ui-spacing/SKILL.md) owns semantic groups, internal/external gap relationships and visible whitespace. The cases below explain how to apply it.
 ![Grouping diagram: equally spaced blocks versus a nested section with smaller inner gaps and larger section separation](assets/ui-design-review/principles-grouping.svg)
 G is the separation from the previous section to the new heading; g connects the heading to its content. Repeated member cards retain the same internal arrangement and gap. Its gap markers describe relationships in one construction, not new global spacing tokens. The crucial relation survives when the page becomes denser: keep the hierarchy between levels rather than subtracting the same amount from every gap.
 <a id="case-title-actions"></a>
 ### Example G1: Separating content from its action group
 **Scene and relationship.** The title is one group and the three actions are another. Inside the action cluster, the icons are peers. A title-to-action gap smaller than the icon-to-icon gaps visually attaches the title to the first icon while separating that icon from its peers.
 **Correction and acceptance.** Reserve the cluster as a unit, use compact regular internal gaps, and leave a distinctly larger title-to-cluster gap. Inspect the visible title ending, not only its flex box. Repeat with a long title, hover, focus, and an open menu; truncation or marquee behavior must not consume the separation.
 <a id="case-team-sections"></a>
 ### Example G2: Spacing between complex sections
 **Scene and relationship.** Member cards form a section; the following “Shared tasks” heading belongs to the task cards below it. The transition must be more evident than the separation within either section, especially when the last member row is only partly filled.
 **Correction and acceptance.** Treat each heading and its content as one section and give the two sections explicit separation. Compare the last member card → task heading gap with the heading → first task gap, using the actual text and card edges. A 2:1 CSS margin ratio is not a substitute for looking. Check one and several member rows, wrapping task text, and the empty-task variant.
 <a id="case-plugin-groups"></a>
 ### Example G3: Nested groups along the reading order
 **Scene and relationship.** The page heading and introduction form one group; search serves the catalog; a subsection heading and its description introduce that subsection's cards. Reusing the same vertical gap at every transition flattens three levels into one sequence.
 **Correction and acceptance.** Keep each heading close to its own explanation, separate page introduction from catalog tools, and keep each subsection closer to its cards than to its neighbor. Repeated subsections reuse this rhythm. Inspect the full stack with a wrapped introduction and expanded cards; do not solve the problem by placing a border around every paragraph.
 #### Primer: equal control widths do not fix a broken reading order
 The [Forms structure comparison](https://primer.style/product/ui-patterns/forms/#structure) contrasts one vertical sequence with a shorter two-column arrangement. In the latter, a long option-group label wraps while unrelated fields start a second reading path. Inspect the sequence and ownership of groups, not just matching input edges.
 | Primer's positive example | Primer's counterexample |
 |---|---|
 | [![Sequential form controls in one reading column](https://user-images.githubusercontent.com/2313998/170069921-98bb9035-2125-4807-b790-1da90e6bde3b.png)](https://primer.style/product/ui-patterns/forms/#structure) | [![The same form split across columns to save vertical space](https://user-images.githubusercontent.com/2313998/170069922-ed8a0ef7-0573-4f02-bd15-da6a5acbc527.png)](https://primer.style/product/ui-patterns/forms/#structure) |
 Images: GitHub Primer, linked from their original sources. Compare the two reading paths and the wrapping option-group label. Apply that grouping judgment to forms throughout the page or modal, including long labels and errors. Related values can share a row when the relation is clear and the pair can stack. These are external examples, not DSH implementation results.
 #### Carbon: different distances carry different meanings
 The [Form specifications](https://www.carbondesignsystem.com/building-blocks/core/components/form/specifications) include an [annotated complete form](https://s3.us-south.cloud-object-storage.appdomain.cloud/cxp-prod-payload-cms/form-style-1.png). Read its title/description, field rows, option group and submit area in order. The example separates the introductory area, repeated fields and final action with different spacing levels while maintaining a common content edge; the annotations make the hierarchy inspectable.
 Use that comparison to review DSH's plugin introduction, search, section description and cards, or a model editor's final action. Compare which elements belong together after adding a line of text. Carbon's numerical scale is evidence for its own example, not a new DSH spacing catalog. A DSH result must also satisfy its existing density, font and responsive rules.
 [![Carbon form anatomy: a shared content edge with distinct title, field and submit spacing](https://s3.us-south.cloud-object-storage.appdomain.cloud/cxp-prod-payload-cms/form-style-1.png)](https://www.carbondesignsystem.com/building-blocks/core/components/form/specifications)
 Image: IBM Carbon Design System. Follow the annotations between the introduction, repeated fields and final action. The image demonstrates its own spacing system; it does not prescribe DSH pixel values.
 <a id="case-sidebar-groups"></a>
 ### Example G4: Separating groups with different purposes
 **Scene and relationship.** “New conversation” is the main action; plugins/automations/more are a global navigation group; the workspace heading introduces the project list. Equal row heights do not express these different relationships.
 **Correction and acceptance.** Keep the navigation rows together, separate that group from the workspace section, and bring the workspace heading closer to the projects it labels. The main action has its own separation. Review the full sidebar with the account area visible; preserve the baseline spacing and role-specific relationships from A1. A larger gap before every project would falsely turn each item into a separate section.
 ### Composed whitespace and responsive grouping
 Identify the layer responsible for group separation, then account for the assembled result: parent gap, child margins, native paragraph margins, heading padding, line-box whitespace, and conditional nodes can accumulate. Compare visible internal and external distances at the same hierarchy level; do not mechanically compare every large internal space against an unrelated outer gap. Initial-content spacing may differ when a heading has a description, but both structures need clear ownership.
 Shared containers should provide stable heading, description, body, and action arrangements that consumers reuse. Do not spread negative margins through consumers to cancel container defaults. Express a concrete role or variant when a different distance is needed, then recheck other shared-container combinations; a tighter local arrangement does not imply compressing every dialog.
 The comparison below shows an actual voice setup dialog. On the left, body and native paragraph margins accumulate and detach guidance from the heading; on the right, the shared description region keeps heading and guidance together while separating actions. This illustrates judging composed relationships, not adopting this dialog's distances everywhere.
 ![Actual dialog comparison: remove accumulated margins and distinguish introductory content from actions](assets/ui-design-review/modal-grouping-comparison.png)
 Reflow complete semantic groups first in narrow containers. If an input squeezes its guidance into a very narrow text column, keep label and guidance together and move that field's input below them; do not shrink every font or move guidance into a neighboring group. Verify actual component width and both sides of the breakpoint, not only browser width. Container queries must work in the assembled application; selectors, CSS module names, or ancestor structure can prevent a plausible declaration from applying.
 <a id="density"></a>
 ## 3. Whole-page density
 Allocate available space to the task's content and controls instead of reducing every gap or font size.
 Density concerns how much useful work fits in the available space and how clearly it is organized. Compact repeatable rows can coexist with generous section gaps. Start with the reading and operating task, not an empty-space percentage. A long list benefits from stable row rhythm; a decision form needs its explanations and validation; an empty page needs a coherent central group rather than the same padding as a populated list.
 When width decreases, preserve semantic groups before shortening labels or moving actions. Wrap complete groups and keep their internal spacing patterns. When height increases, decide which region should expand; fixed gaps alone do not place an empty state. Inspect both excessive compression and excessive separation. A dense page is acceptable when comparison remains easy; a sparse page can still have poor grouping.
 <a id="hierarchy"></a>
 ## 4. Information hierarchy
 Make the next reading or decision step visible without turning every text element into a heading.
 Use emphasis to express a task-relevant difference. A current selection, an actionable error, and the data needed for a decision deserve stable recognition. Labels and supporting metadata can be quieter, but making useful text difficult to read is not hierarchy. Inspect size, weight, color, position, and surrounding whitespace together; piling all five onto every heading removes meaningful contrast.
 Use the [icon owner](../.agents/skills/dsh-ui-icons/SKILL.md) for icon/label foreground roles and their semantic exceptions; example C1 applies that rule to search fields.
 Typography participates in geometry: compare text starts, baselines and line boxes with the intended font, long translations and relevant font preferences. Pair size with line height and use the weight limits from [visual foundation](../.agents/skills/dsh-client-ui-ux/references/visual-foundation.md). Content, code, terminal and fixed interface roles need not scale identically; check the [font-setting owner](../packages/client/ui-theme/README.md) before treating a deliberate difference as a defect. Correct the container allocation before shrinking useful text to force alignment.
 <a id="case-search-color"></a>
 ### Example C1: Color emphasis within one information unit
 **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.
 <a id="states"></a>
 ## 5. Control states
 Persistent state and transient feedback must remain distinguishable when they occur together.
 State design assigns stable meanings, not just different colors. Selection says “this is the current item”; hover says “the pointer is here”; focus says “keyboard input goes here”; disabled says “this action is unavailable.” Compare simultaneous states and adjacent items: the selected row beside a hovered unselected row matters as much as selected-plus-hover on one row.
 | Combination | What must remain legible | Failure to look for |
 |---|---|---|
 | Selected + another row hovered | Current location remains recognizable | The temporary row looks more selected than the current row |
 | Selected + hover on the same item | Selection persists while interaction feedback appears | A generic hover fill erases the current state |
 | Selected + keyboard focus | Location and keyboard target remain distinguishable | Focus disappears into the selection treatment |
 | Selected + disabled | Retained choice and temporary unavailability both remain visible | Fading the item makes it look deselected |
 | Expanded + menu open | The active operation has a clear owner | A panel highlight and row highlight compete without a stable relationship |
 <a id="case-sidebar-state"></a>
 ### Example S1: Persistent selection beside temporary hover
 **Scene and relationship.** Compare the selected conversation, a neighboring hovered row and an open row menu against the master baseline. Background paint is one cue alongside the current-row semantics and revealed actions; selection and hover do not require different colors.
 **Correction and acceptance.** Preserve the master state treatment and verify that selection persists when hover ends or a menu closes. Move between neighboring rows and traverse by keyboard; inspect focus, action visibility and current-row semantics together. Do not introduce a stronger selected fill solely to satisfy this example. Compare the same theme and platform material; an opaque fixture cannot establish translucent Desktop contrast.
 <a id="component-choice"></a>
 ## 6. Component choice
 Choose the component from the interaction it represents, then fit its layout to the available space.
 Choose the element by what users can do, then make peers visually coherent. Navigation opens a destination, a toggle changes a setting, a checkbox adds an independent choice, and an action button starts an operation. Similar geometry does not make these interchangeable. A card adds a containing group and more space; it is justified when that group needs an independent summary, state, or action, not merely because a row looks plain.
 Keep the control's label, visible bounds, focus behavior, and click target consistent with the chosen interaction. If a visual correction changes those semantics, it needs behavior review as well. Geometry and radius are judged separately in [section 8](#geometry); “native control” is neither a guarantee of visual fit nor a reason to discard keyboard and accessibility behavior.
 <a id="icon-optics"></a>
 ## 7. Icon optics
 The [icon skill](../.agents/skills/dsh-ui-icons/SKILL.md) owns interface icon roles, slots, color and optical balance. [Official artwork](../.agents/skills/dsh-official-plugin-artwork/SKILL.md) retains its separate role.
 <a id="case-file-optics"></a>
 ### Example O1: Optical alignment of different icon types
 **Scene and relationship.** At one tree depth, compare closed/open folders, native file-type icons, generic files, and names without icons. Then compare the same pattern one level deeper.
 **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.
 <a id="geometry"></a>
 ## 8. Control geometry and corner relationships
 Consistency means that equal roles and size variants follow one rule, and different roles have an understandable relationship. Review outer height, width, radius, curve, inset, and visible base together. Legal tokens can produce an incoherent combination; one radius on every element can be equally incoherent. The [radius standard](ui-radius.md) owns values and nested geometry, so this section does not create another scale.
 Distinguish a tightly inset surface that follows its container from an independent card inside a panel. The first needs coordinated outer/inner curves and inset; the second follows its own component role. Check the background, border, highlight, pseudo-elements, and clipping together. A hover fill that changes the visible silhouette is a state defect even if the resting border is correct.
 ### Decide geometry in this order
 Classify the semantic role, select its existing size variant, identify the parent/child relationship, then inspect curve, material and state. The [radius scale](ui-radius.md#radius-scale) and its named exceptions supply values; a larger bounding box after expansion does not select a new tier. Equal radius numbers can still look different when height or curve differs.
 | Relationship | Decision from the radius owner | Visual failure to look for |
 |---|---|---|
 | Circular concentric inset | Inner radius is outer radius minus inset, clamped at zero; arcs share a center | Same-radius inner/outer corners pinch or widen the visible band |
 | Nested superellipses | Use the shared nominal size relation, then inspect diagonal spacing; they are not exact offset curves | Claiming mathematically equal spacing from subtraction alone |
 | Flush fill or adjoining segments | The enclosing silhouette owns exposed corners; internal joins stay square | Notches, crescents, double contours or focus clipped with the fill |
 | Independent child card/group | Choose its role tier instead of subtracting all surrounding space | Collapsing a legitimate child radius to zero from large parent padding |
 | Explicit circle or pill | Preserve round arcs for the container and its painted contents | A rounded avatar container holding a noncircular image; squircle-like capsule ends |
 Compare fill, stroke, hover overlay, focus and clipping together throughout the page or modal. Flat card borders and elevated materials have different paint ownership under [Web styling](web-styling.md#component-rules); applying both can double the edge. When a contour clips its fill, keep popups and keyboard focus fully visible. Inspect the geometry and continued use together.
 #### Fluent: the split-button notch is a relationship error
 The [Shapes example](https://fluent2.microsoft.design/shapes/#when-to-avoid-rounded-corners) marks the gap where two separately rounded button halves meet. Inspect the internal seam rather than the outer corners: treating each half as a complete independent silhouette breaks the shared enclosure. This is a concrete negative example, not a recommendation to make every control rounder.
 [![Fluent's negative example: two rounded halves create an unwanted internal notch](https://fluent2.microsoft.design/_image?f=png&h=440&href=https%3A%2F%2Ffluent2websitecdn.azureedge.net%2Fcdn%2Fdesignlanguage-shapes-cornerradius-03.D70MlS4K.webp&w=728)](https://fluent2.microsoft.design/shapes/)
 Image: Microsoft Fluent 2, linked from its original source. In DSH, apply the flush-fill arrangement from the radius standard, then check independent hover regions, focus and the fully visible popup together. Fluent's radius and stroke scale are not DSH defaults. Look at the notch at the internal seam; this source image is a negative example, not a DSH before/after comparison.
 <a id="case-model-radius"></a>
 ### Example R1: Radii across container and control roles
 **Scene and relationship.** A model editor contains grouped model rows, two inputs per row, an “Add model” button, and cancel/save actions. Every corner appears on the same screen, so role and size relationships must be readable together.
 **Correction and acceptance.** Classify the outer editor, model group, field, and button before selecting their existing variants. Same-role controls at the same size match. Coordinate tightly nested curves with actual inset, while independent children retain their own role. Check collapsed/expanded rows, field focus, hover fills, and long model names. Do not justify a random radius by pointing to the total height after expansion.
 <a id="case-checkbox-radius"></a>
 ### Example R2: Small selection controls within a form
 **Scene and relationship.** Input-type choices use dark native checkboxes beside rounded form controls. The mismatch concerns the small control's silhouette and visual weight, not a requirement to give a checkbox the radius of a large input.
 **Correction and acceptance.** Use a coherent small-selection-control treatment while preserving the recognizable checkbox silhouette and label association. If native appearance is replaced, retain checked/unchecked, disabled, keyboard focus, and assistive semantics. Compare these states at actual size in both themes; an unchecked outline and its checked fill must belong to the same control family.
 <a id="case-automation-radius"></a>
 ### Example R3: Justified geometry differences between roles
 **Scene and relationship.** Nearby automation controls combine rounded filter chips, a search field, and a primary create action. Similar control heights can still produce a conspicuous jump in roundness when each feature chooses its own radius.
 **Correction and acceptance.** Reuse the established control variants. A true pill is an explicit component type; it does not authorize every compact button to use half its height as radius. Compare filters, search, and primary/secondary buttons in one frame. Check hover and focus contours too. Keep a meaningful pill/field distinction where intended rather than forcing equal radii solely because the controls share a row.
 <a id="reproduce"></a>
 ## Reproduce and compare
 Locally maintained production-component fixtures can supply isolated examples for repeatable content and state. Derive actual application captures from the whole page or modal under review, including its relevant regions and states. A fixture establishes only what it renders; it does not determine or complete the review scope.
 The dimensions found in these components are evidence about those examples, not universal design constants. The [style reference](web-styling.md), [radius standard](ui-radius.md), and component owners retain authority over shared values. Extend the evidence for new consumers or a different task rather than copying an example's number without its conditions.
 <a id="references"></a>
 ## External references and what DSH adopts
 These are research inputs, not automatically invoked skills or replacements for DSH rules. The selection below was read on 2026-10-26. Public guidance supplies comparison methods; the worked DSH cases and explanatory diagrams are local synthesis. Links point to the original authors. No external skill installation or execution is required to use this reference.
 | Reference | Useful contribution | Scope and deliberate limit |
 |---|---|---|
 | [Anthropic frontend-design](https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md) | Explicit composition, content-specific choices, and rendered self-critique | Its expressive visual direction is not a mandate to restyle a workbench or change DSH typography |
 | [Vercel web-design-guidelines skill](https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md) and [rules](https://github.com/vercel-labs/web-interface-guidelines/blob/main/command.md) | Locate findings in code and cover focus, labels, long content, and interaction | Code compliance alone does not establish alignment or grouping; its title-case advice does not override DSH sentence case |
 | [Impeccable](https://github.com/pbakaus/impeccable/blob/main/.agents/skills/impeccable/SKILL.md), [critique](https://github.com/pbakaus/impeccable/blob/main/.agents/skills/impeccable/reference/critique.md), [polish](https://github.com/pbakaus/impeccable/blob/main/.agents/skills/impeccable/reference/polish.md), [operate](https://github.com/pbakaus/impeccable/blob/main/.agents/skills/impeccable/reference/operate.md) | Separate a task-oriented interface from promotional design; distinguish visual judgment from detector output | Adopt the complete-path inspection and existing-system comparison, not its execution, delegation, or scoring machinery |
 | [Interface Design](https://github.com/Dammyjay93/interface-design/blob/main/.claude/skills/interface-design/SKILL.md) | Explicit product intent, repeated patterns, and comparison with established neighboring interfaces | Preserve DSH's existing system; do not import its example font weights, create another token catalog, or chase novelty for its own sake |
 | [OpenAI figma-implement-design](https://github.com/openai/skills/blob/main/skills/.curated/figma-implement-design/SKILL.md) | Compare rendered output against an actual visual reference and integrate existing components | A screenshot is evidence with a defined scope, not permission to infer unseen states or adopt every number |
 | [Fluent Shapes](https://fluent2.microsoft.design/shapes/) and [Primer Forms](https://primer.style/product/ui-patterns/forms/) | Explicit component counterexamples with inspectable relationships | The case analyses above transfer a decision method, not their token or interaction system |
 | [Atlassian spacing](https://atlassian.design/foundations/spacing/) | Positive/negative examples of proximity, repeated rhythm, hierarchy, and optical adjustment | Borrow the relationship tests, not Atlassian's token names or an automatic pixel formula |
 | [Carbon spacing](https://www.carbondesignsystem.com/building-blocks/foundations/spacing/overview) | Spacing patterns express equal weight and section boundaries; fluid centering differs from fixed spacing | Use DSH's spacing ownership; a scale alone cannot select the right group relationship |
 | [Codex official product introduction](https://openai.com/index/introducing-the-codex-app/) and [desktop documentation](https://learn.chatgpt.com/docs/app) | Task-oriented composition and real public examples to compare | Public examples are versioned observations, not the current local app or an unpublished Codex design specification |
 ### Codex: a limited reference for composition
 The official [welcome/composer poster](https://learn.chatgpt.com/images/codex/video-posters/proactive-teammate-v2.webp) and [long-input poster](https://learn.chatgpt.com/images/codex/video-posters/draft-prds-from-slack-linear-docs.webp) show centered introductory content, left-aligned input text, and separate bottom control groups. They support that composition comparison. They do not reveal full-sidebar alignment, nested-corner behavior, neighboring selected/hovered states, or resizing. Use the more specific examples above for those decisions rather than treating a product poster as broad design approval.
 External images remain at their credited sources. If a source image is unavailable, the adjacent analysis still identifies the comparison; obtain a usable reference before using that image as visual evidence in a new review.
 <a id="dev-note"></a>
 ## Dev Note
 None.
@@ -0,0 +1,423 @@
 ---
 description: "DSH 设计判断参考：对齐、空间分组、信息层级、状态与几何，以及完整的审查案例。"
 ---
 # UI 设计原则与审查案例
 [English](ui-design-review-cases.md) | 中文
 ## 概览
 用本参考把整页或整个弹窗作为一个视觉整体审查。在所有区域之间统一判断对齐与空间分组，同时比较层级、状态、颜色、尺寸和圆角。下文例子解释可以迁移的关系，不限定要审查哪些页面；参考图紧接对应分析展示。执行流程与证据要求见[审查 cookbook](cookbook/reviewing-ui-design.zh.md)。
 ## 目录
 - [审查究竟要判断什么](#judgment)
 - [以整页或整个弹窗作为审查单位](#whole-interface-review)
 - [适用的 DSH 规范](#review-baseline)
 - [如何用例子理解原则](#case-selection)
 - [原则示例索引](#case-index)
 - [1. 对齐](#alignment)
 - [2. 空间分组](#grouping)
 - [3. 整屏密度](#density)
 - [4. 信息层级](#hierarchy)
 - [5. 控件状态](#states)
 - [6. 组件选型](#component-choice)
 - [7. 图标光学](#icon-optics)
 - [8. 控件几何与圆角关系](#geometry)
 - [复现与比较](#reproduce)
 - [外部参考与 DSH 的取舍](#references)
 - [开发备注](#dev-note)
 <a id="judgment"></a>
 ## 审查究竟要判断什么
 好的界面会在读者逐字阅读前先表达元素之间的关系。对齐让人比较并列内容时不用反复寻找起点；间距告诉人哪些图标、标签、说明、控件和操作属于同一组。这些是基础设计要求，即使功能完全可用也要满足，不能等 token 检查通过后才当作可选打磨。
 DSH 的视觉审查优先关注对齐与空间分组。先识别任务和语义组，再检查整个区域的跨组对齐轴，然后检查每组内部关系；随后检查信息层级、状态、几何、颜色、密度和光学细节。操作阻塞或误导性状态仍先于纯外观问题。不能为了统一而让所有元素一样大、一样疏密、一样突出。
 页面或弹窗提供构图参照；一次改动需要检查哪些关系，由[影响范围](cookbook/reviewing-ui-design.zh.md#review-scope)决定。导航、内容、表单和操作即使由不同组件实现，也可能共用文字轴和间距规则。例外应由角色、层级或状态解释，组件归属本身不是设计理由。
 本文原理图解释元素关系，不是实现截图或已验收的修改前后对照。下文例子用于讲清具体原则，不代表已覆盖当前要审查的页面或弹窗。
 <a id="combined-cases"></a>
 <a id="whole-interface-review"></a>
 ## 以整页或整个弹窗作为审查单位
 选择参照和判断关系时，将整个页面或弹窗视为一个视觉整体。日常改动在这个上下文中审查受影响的分组和跨组关系，不自动检查每个区域或整个产品。明确的完整界面审查必须检查其全部区域。侧栏、表单、工具栏即使由独立组件实现，也属于更大的整体构图。
 对弹窗，标题、关闭按钮、全部内容分区、滚动区域和底部操作一起纳入判断；对页面，导航、页头、工具栏、内容区和固定操作一起纳入判断。滚动后才能看到的内容仍属于同一个整体。选择对齐和居中参照时，依据页面或弹窗自己的边缘；打开的弹窗在底层页面之上形成自己的构图。
 ### 从整体、组间关系看到组内元素
 先看整体构图：内容边缘、视觉中心、阅读顺序、主操作和总体疏密。再按内容描述什么、操作什么，判断哪些元素组成一组、组内有哪些子组。先比较相邻组，再看组内元素。同一种关系应在整页或整个弹窗内保持一致，包括相距较远的分区。
 | 审查方面 | 在整页或整个弹窗内统一比较 | 判断依据 |
 |---|---|---|
 | 对齐 | 文字起点、图标中心、控件边缘、重复的操作列 | 按角色选择居左、居中或两侧对齐；共用轴线跨组延续；图标与文字先作为一个单元判断 |
 | 空间分组 | 标签到内容、元素之间、组之间、分区之间的距离 | 组内间距小于组间间距；组越复杂，组间距应越大；相似构成的组复用相同组内间距 |
 | 尺寸与比例 | 同角色控件、图标底板、图标及相邻文字 | 使用一致的尺寸变体和视觉重量；必要时通过调整大小实现共同对齐 |
 | 圆角与轮廓 | 外层容器、卡片、字段、按钮和选择控件 | 全部遵循同一套按角色划分的圆角规则；依据已有规范区分内缩、贴边和独立容器关系 |
 | 颜色与强调 | 文字、关联图标、底色、描边和辅助信息 | 共同表达同一信息的图标与文字保持一致的强调；差异应能由角色或状态解释 |
 | 字体与疏密 | 标题、标签、说明、重复行和整体留白 | 同层级内容保持一致，层级清楚；局部间距与整体疏密协调 |
 | 状态与行为 | 选中、悬停、焦点、禁用、展开、加载和失败内容 | 状态变化后仍能认出分组、对齐关系和操作入口；同时出现的状态放在一起比较 |
 统一看待，意味着在这个范围内使用同一套判断依据。同角色、同尺寸变体使用一致处理，差异来自角色、层级或状态。“由不同组件实现”不能解释文字起点、间距模式或圆角为什么不一致。同样，居中的标题与居左的阅读列可以共存，前提是各自角色支持这种构图。
 ### 把每个发现放回整体判断
 记录哪些元素发生冲突、它们应共享什么关系，以及改法如何与页面或弹窗的其他部分协调。在本次范围内比较这种关系的所有出现位置。局部调整后，回到整体构图，一起复查受到影响的对齐、分组、几何和层级。
 完整审查覆盖范围内所有区域，包括相关滚动位置、展开内容、标签页，以及会改变这些关系的状态。按适用情况检查支持的宽度、主题和输入方式。保留草稿、焦点、关闭方式和主操作可达性，失败时提供相应恢复。没有检查的区域和状态明确列出。一张合格裁图、一个组件 fixture 或几个选定例子，都不能证明整页或整个弹窗已经协调一致。
 ### 用关系清单判断覆盖是否完整
 把完整界面中的语义组列出来，再列出需要比较的关系：父子缩进、跨分区文字列、重复操作槽、标题与说明、字段与校验、正文与行内控件、滚动内容与固定操作。不只检查每组内部；每条跨组关系都必须连接到实际比较过的两端。修改共用原语时，补查它在有／无说明、长短内容和不同操作组合中的使用方。
 关系通过至少满足三项：结构使用同一个参照；实际画面表达该关系；改变相关内容或状态后仍成立。测试断言存在、同一个 token、截图成功或单张裁图都不能单独替代这三项。优先级按误导程度、使用频率及传播范围决定，不能用“只差几像素”排除高频错列。
 “已检查无新增问题”“已修复并复查”“发现但未修复”“未检查”分别记录。若无法穷尽平台或异常状态，交付明确的覆盖边界；不能将例子数量、组件测试数量或页面入口数量当成全部设计通过。
 <a id="review-baseline"></a>
 ## 先综合适用规范
 用[规则归属表](../.agents/skills/dsh-client-ui-ux/SKILL.md#select-the-rule-owners)选择当前实现要求，包括对齐、间距和图标专项。
 审查有两个独立要求：符合适用的 DSH 规则，同时解释组装后的界面是否清楚表达预期关系。轮廓好看不能抵消交互语义错误，token 合法也不能抵消对齐错误。局部审查应明确不涉及哪些方面；整体审查则在受审整页或整个弹窗的所有区域中检查下表相关项。
 | 规则所有方 | 对审查的贡献 | 在整页或整个弹窗中比较什么 |
 |---|---|---|
 | [圆角规范](ui-radius.zh.md#radius-scale)、[嵌套几何](ui-radius.zh.md#nested-hover) | 先角色后尺寸；内缩、贴边填色、独立子容器三种关系；曲线与明确例外 | 外层容器、字段、hover 填色、指示块及裁切边缘一起比较 |
 | [Web 样式](web-styling.zh.md#component-rules) | 语义色、字号与行高配对、发丝线、层级阴影、菜单材质、动效 | 跨功能的同角色表面、明暗主题与 Desktop 原生背景 |
 | [客户端 UI/UX skill](../.agents/skills/dsh-client-ui-ux/SKILL.md) | 组件复用、层级、加载、反馈归属、窗口避让 | 加载后／空／错误状态及实际周边页面 |
 | [响应式 skill](../.agents/skills/dsh-responsive-ui/SKILL.md) | 先分配空间再截断、输入能力、焦点、主操作可达性 | 同一任务的宽屏、受限宽度、键盘及触屏使用 |
 | [官方图案 skill](../.agents/skills/dsh-official-plugin-artwork/SKILL.md) | 插件图案语义、光学平衡、透明区域及邻近参照 | 插件图案在列表与详情中的呈现；操作图标属于另一类 |
 | [错误处理 skill](../.agents/skills/dsh-error-handling/SKILL.md#localized-actionable-visible-reports) | 失败可见、保留有效状态、提供安全下一步 | 区分字段纠错、操作失败与查询失败 |
 | [基础组件目录](../packages/client/ui-primitives/README.zh.md#component-catalog)与相关包 README | 已有变体、焦点与交互行为、功能特有要求 | 实际组件角色与外观相似的替代品是否相符 |
 当前仓库所有方及其明确记录的例外，优先于旧版个人 skill 或外部案例。用户的具体选择适用于指定组件族，不会默默替换全局体系。实现与所属规范不一致时，报告差异，不能把既有代码自动当成新规则。选圆角和材质时重新核对所有方，不在 review 文档里复制另一套尺度。
 <a id="case-selection"></a>
 ## 如何用例子理解原则
 例子通过具体任务、相关元素、周边上下文，以及可能推翻改法的变化条件，让原则变得可观察。应提炼其中的关系，并用于当前整页或整个弹窗的判断。侧栏或模型编辑器的例子，不会把原则限定在这些组件上。例子是帮助理解的证据，不是审查菜单或覆盖清单。
 区分三种证据：DSH 实际场景可以确认所展示条件下的缺陷；官方设计系统案例解释特定关系，其尺寸与交互策略仍属于原系统；原创示意图解释拟采用的关系，不能标成已实现的改善。fixture 仅覆盖它渲染的条件。来源、比较对象、适用的 DSH 规则和复查条件应当紧邻案例。
 每个案例按“场景与问题 → 设计判断 → 紧接下方的截图或成对对照”呈现。图注说明看哪里、两侧分别表示什么及来源。不要把无关案例集中成脱离正文的截图墙。差异只有勉强可辨、或图片没有包含所讨论关系时，应选择更有解释力的证据，不能将其当作设计范例。
 <a id="case-index"></a>
 ## 原则示例索引
 对某种关系不确定时，可借助这些例子理解。在当前页面或弹窗内，所有相关区域都适用相同原则，包括这里没有举到的区域。审查范围来自用户要求的界面，不由这份示例清单决定。
 | 案例 | 要检查的关系 |
 |---|---|
 | [A1](#case-sidebar-axes) | 按角色判断侧栏对齐 |
 | [A2](#case-action-columns) | 重复操作组的对应列 |
 | [A3](#case-preview-toolbar) | 多排控件与复合控件的对齐 |
 | [A4](#case-empty-center) | 内容组相对所属容器居中 |
 | [A5](#case-composer-controls) | 并列控件的可见尺寸与中心 |
 | [G1](#case-title-actions) | 内容与操作组的分隔 |
 | [G2](#case-team-sections) | 复杂分区之间的间距 |
 | [G3](#case-plugin-groups) | 阅读顺序中的多层分组 |
 | [G4](#case-sidebar-groups) | 不同用途的组之间的分隔 |
 | [C1](#case-search-color) | 同一信息单元的图文强调 |
 | [S1](#case-sidebar-state) | 持续选中与临时悬停共存 |
 | [O1](#case-file-optics) | 不同类型图标的光学对齐 |
 | [R1](#case-model-radius) | 不同层级容器与控件的圆角 |
 | [R2](#case-checkbox-radius) | 表单中小型选择控件的轮廓 |
 | [R3](#case-automation-radius) | 不同角色之间有依据的几何差异 |
 <a id="alignment"></a>
 ## 1. 对齐
 [对齐 skill](../.agents/skills/dsh-ui-alignment/SKILL.md)负责共享轴线、完整布局框、层级缩进和文字度量；以下案例用于说明这些判断。
 ![对齐示意：同类行共享轴线，账号和标题操作保留各自几何关系](assets/ui-design-review/principles-alignment.svg)
 示意图区分同类行的轴线与账号、标题区域的几何关系，不是像素规范。[侧栏基线](../.agents/skills/dsh-ui-alignment/SKILL.md#sidebar-design-baseline)负责当前关系。分别比较内容、背景绘制区域和点击区域；不同角色不必共用所有轴线。
 ### 文字度量与不等长内容
 行内图标的参照是相邻文字，不是整段的行框中心。`cap-height` 可以用于具体字体组合的校准，但不是所有字体与图标的统一公式；不能把某次有效的位移复制到所有控件。多行说明旁的状态图标通常附着首行，而单行按钮的 icon 与 label 作为整体居中。改变字号、字体回退或语言后重新检查这种关系。
 下图使用真实 Markdown 渲染，左前右后，标注只在右图。中文、英文和代码链接保持原图标尺寸，通过字体度量修正垂直位置；外部留白与组内留白分别负责链接归属。检查长链接时还需看完整段落中的换行，裁图不能证明长链接可用。
 ![行内链接实际对比：图标与相邻字体对齐，保留框内留白](assets/ui-design-review/inline-metrics-comparison.png)
 并列卡片应共同确定标题起点、说明首行和操作区边缘。短说明不因相邻说明更长就独自垂直居中；剩余高度放在内容组之后，底部操作可以另行对齐。统一卡片高度不等于统一内部阅读顺序，也不要求裁短真实内容来制造等高。
 下图为实际预设卡片的长短内容组合。左侧短说明因自动外距离开标题，右侧说明共同从标题下方开始，操作区仍对齐。该关系也适用于结果卡片、选项卡片和并列摘要；它不要求所有页面都采用卡片。
 ![并列卡片实际对比：说明首行对齐，底部操作保持对齐](assets/ui-design-review/peer-content-comparison.png)
 <a id="case-sidebar-axes"></a>
 ### 示例 A1：按角色判断侧栏对齐
 **场景与关系。**对照已记录的 master 基线，比较展开侧栏中的导航、工作区行、会话和账号区域。检查居中的新会话操作与行背景边缘，而不只比较文字起点。
 **错误与修正。**为所有角色套用同一前导槽宽度，会移动标题、拉大间距或改变已登录账号行。保留所属组件的共享变量、紧凑图标槽和绘制内缩。保留有意设计的账号几何关系与层级，不强造贯穿所有角色的文字轴。
 **验收。**只为基线已建立的关系绘制辅助线。检查长短标题、可选图标、项目展开和账号登录／未登录状态。行操作浮现不能移动标题起点。列表裁图不能证明完整侧栏对齐。
 <a id="case-action-columns"></a>
 ### 示例 A2：区分标题操作与行操作
 **场景与关系。**工作区的搜索／筛选／添加与会话的更多／归档／置顶都处于侧栏尾部，但角色和间距不同。重复行之间互相比较；标题区域则比较自身搜索收起和展开的状态。
 **错误与修正。**强迫两组共用三槽网格会改变 master 设计。保留各组的控件尺寸、间距、尾部内缩与搜索过渡。标题到操作组的分隔独立于组内间距。
 **验收。**同时显示标题与行操作，再展开搜索并折叠侧栏。检查预期边缘关系、未裁切的点击区域和长标题避让。不能为了让无关控件形成垂直列而补空操作或偏移。
 <a id="case-preview-toolbar"></a>
 ### 示例 A3：多排控件与复合控件的对齐
 **场景与关系。**面板控制位于上排，文件显示控制与“在应用中打开”分段按钮位于下排。两排属于同一个预览页头，每排又包含作用范围不同的操作。
 **错误与修正。**各组件内部可能已经居中，组装后仍出现无关的右边距、高度和分组间距。先按上排图标框与下排完整控件建立尾端关系，保留图标内部留白；不能直接对齐额外热区，也不能追齐单个 glyph 的像素边缘。再对齐并列控件中心，把显示控制收成一组，与外部打开操作分开。分段按钮按完整单元处理，不强迫其箭头与无关的面板操作共用列轴。
 **验收。**保留路径、标签页与内容边缘，一并观察两排；再检查长路径和窄面板。用一排独立图标代替实际分段控件，不能验证这个关系。
 <a id="case-empty-center"></a>
 ### 示例 A4：内容组相对所属容器居中
 **场景与关系。**自动化页面在标题、筛选栏下面放置插画、说明和创建按钮。空状态组属于剩余内容区，应具有共同的水平中心和明确的纵向位置。
 **错误与修正。**各子项水平居中，但父级只设置固定顶部 padding，会让整组停在高视口上方。让内容区占据剩余高度，再定位完整内容组；同时检查内部节奏，不能只移动按钮来声称整组居中。
 **验收。**标出剩余内容矩形与整组的外接范围，以同样内容比较高、矮、窄窗口。区分有设计依据的光学偏移与意外固定间距；侧栏或页头改变可用区域时，不要求相对于整个窗口居中。
 <a id="case-composer-controls"></a>
 ### 示例 A5：并列控件的可见尺寸与中心
 **场景与关系。**附件和发送操作分别位于底栏两端。DSH 的预期处理是圆形底板等大、垂直中心一致，主次通过填色与状态表达。
 **错误与修正。**底板直径不同，再加额外的垂直平移，会形成两个不一致的端点。先统一并列控件外部几何并去掉布局补偿，再平衡槽内的加号和箭头。细线加号与实心箭头不需要具有相同的墨迹面积。
 **验收。**检查空输入、可发送、忙碌／停止和窄布局中的底板与中心。保留输入框外轮廓一起观察，不能只看两张独立按钮截图。参考产品里不同大小的操作控件，不能覆盖 DSH 已明确的等大底板要求。
 <a id="grouping"></a>
 ## 2. 空间分组
 [间距分组 skill](../.agents/skills/dsh-ui-spacing/SKILL.md)负责语义组、组内外间距关系和可见留白；以下案例说明如何应用。
 ![分组示意：等间距堆叠与分层分组的区别，组内较近，分区之间更远](assets/ui-design-review/principles-grouping.svg)
 图中 G 是前一个分区到新标题的间距，g 是新标题到所属内容的间距；重复成员卡片保持相同的内部排列与间隔。间距标记只描述这张构造图中的关系，不增加全局间距 token。页面变密时仍须保留层级关系，不能对每种间距都减去相同数值。
 <a id="case-title-actions"></a>
 ### 示例 G1：内容与操作组的分隔
 **场景与关系。**标题是一组，三个操作图标是另一组，图标之间是并列关系。标题到操作的距离比图标之间还小，会把标题与第一个图标视觉上粘在一起，反而把该图标与其他操作分开。
 **修正与验收。**将操作组作为整体预留空间，组内采用紧凑且一致的间距，标题到操作组之间明显更宽。观察可见标题的末端，而非只看 flex 框。覆盖长标题、悬停、焦点和菜单打开状态；截断或滚动文字不能侵占分组留白。
 <a id="case-team-sections"></a>
 ### 示例 G2：复杂分区之间的间距
 **场景与关系。**成员卡片组成一个分区，随后“共享任务”标题属于它下方的任务卡片。两个分区之间的过渡应比各区内部的间隔更清楚，尤其是在最后一排成员卡片未填满时。
 **修正与验收。**将每个标题及其内容作为一个完整分区，明确设置分区间距。按实际字面和卡片边界，比较“最后一张成员卡片 → 任务标题”与“任务标题 → 第一张任务卡片”的距离。CSS margin 的 2:1 比例不能替代读图。检查一排和多排成员、任务文案换行、任务为空的变体。
 <a id="case-plugin-groups"></a>
 ### 示例 G3：阅读顺序中的多层分组
 **场景与关系。**页面标题与介绍是一组，搜索服务于目录，子分区标题与说明介绍该分区的卡片。每次过渡都沿用相同纵向间距，会把三个层级摊平成一串元素。
 **修正与验收。**各标题靠近自己的说明，页面介绍与目录工具分开，每个子分区与自己的卡片更近、与相邻分区更远。重复分区复用同一节奏。检查完整纵向序列，包含介绍换行和卡片展开；不能用给每段文字套边框来替代分组。
 #### Primer：控件等宽不能修复阅读顺序
 [Forms 结构对照](https://primer.style/product/ui-patterns/forms/#structure)将纵向连续表单与更矮的两列表单并列。后者的长选项组标签换行，同时无关字段开启另一条阅读路径。应该比较顺序和分组归属，不能只检查输入框边缘是否齐整。
 | Primer 正例 | Primer 反例 |
 |---|---|
 | [![沿单一阅读列连续排列的表单控件](https://user-images.githubusercontent.com/2313998/170069921-98bb9035-2125-4807-b790-1da90e6bde3b.png)](https://primer.style/product/ui-patterns/forms/#structure) | [![为节省纵向空间而拆成两列的同一表单](https://user-images.githubusercontent.com/2313998/170069922-ed8a0ef7-0573-4f02-bd15-da6a5acbc527.png)](https://primer.style/product/ui-patterns/forms/#structure) |
 图片来自 GitHub Primer，链接到原始来源。比较两条阅读路径和换行的选项组标签，将这种分组判断用于整页或整个弹窗中的表单，包括长标签和错误。相关字段在归属清楚、整组能换行时可以同行。这些是外部参照，不是 DSH 实施结果。
 #### Carbon：不同距离表达不同关系
 [Form 规范](https://www.carbondesignsystem.com/building-blocks/core/components/form/specifications)提供[完整表单的标注图](https://s3.us-south.cloud-object-storage.appdomain.cloud/cxp-prod-payload-cms/form-style-1.png)。依次读标题／说明、字段行、选项组与提交区。示例为介绍区、重复字段、末尾操作使用不同层级的距离，同时保留共同内容边缘；标注使层级可以直接比较。
 用这个关系审查 DSH 插件页的介绍、搜索、分区说明、卡片，或模型编辑器的末尾操作。增加一行文字后，再比较哪些元素仍然属于同一组。Carbon 数值属于它自己的示例，不是新的 DSH 间距目录；DSH 的结果还要满足既有密度、字号和响应式规则。
 [![Carbon 表单解剖：共同内容边缘，以及标题、字段、提交区的不同间距](https://s3.us-south.cloud-object-storage.appdomain.cloud/cxp-prod-payload-cms/form-style-1.png)](https://www.carbondesignsystem.com/building-blocks/core/components/form/specifications)
 图片来自 IBM Carbon Design System。沿标注比较介绍区、重复字段和末尾操作之间的间距；图中展示其自身的间距体系，不规定 DSH 的像素数值。
 <a id="case-sidebar-groups"></a>
 ### 示例 G4：不同用途的组之间的分隔
 **场景与关系。**“新会话”是主操作，插件／自动化／更多组成全局导航，工作区标题介绍项目列表。相同行高不能表达这几种不同关系。
 **修正与验收。**导航行彼此靠近，导航组与工作区分开，工作区标题更靠近它所标注的项目，主操作与导航组保留独立间隔。连同账号区域检查完整侧栏；保留基线间距及 A1 按角色区分的关系。在每个项目前都增加大间距，会错误地把每个项目变成独立分区。
 ### 组合后的留白与响应式分组
 先确认哪一层负责组间距离，再核算实际组合：父级 gap、子级 margin、原生段落外距、标题 padding、行框空白和条件节点都可能叠加。组内可见距离与组间可见距离应在同一层级比较；不能把一组内部最大的所有空白与任意外部 gap 机械比较。标题带／不带说明时，首次内容的距离可以不同，但两种结构均需明确归属。
 公共容器应提供稳定的标题、说明、正文和操作组织方式，使用方优先沿用。不要在使用方普遍增加负 margin 去抵消容器默认值。确需不同间距时，表达具体角色或变体，再复查共享容器的其他组合；局部更紧凑不等于所有弹窗都应压缩。
 下图是实际语音提示弹窗。左侧普通段落叠加正文与原生外距，使说明脱离标题；右侧使用公共说明区，标题与解释更紧密，独立操作保留分隔。它说明间距应由组合后的关系决定，不规定全部弹窗采用这张图的距离。
 ![弹窗实际对比：去除重复外距，明确标题说明组与操作区](assets/ui-design-review/modal-grouping-comparison.png)
 窄容器首先重排完整语义组。若输入框挤压说明成极窄文字列，将标签与说明留在一起，并把该字段的输入放到下一行；不要缩小所有字体或让说明跨到邻组。验证组件实际容器宽度和断点两侧，而不只改变浏览器宽度。容器查询须在真实组装中生效；选择器、CSS module 名称或祖先结构都可能使看似正确的声明不起作用。
 <a id="density"></a>
 ## 3. 整屏密度
 按任务内容与控件分配可用空间，不是缩小所有间距或字号。
 密度关注可用空间能容纳多少有效工作，以及这些内容是否组织清楚。紧凑的重复行可以与宽松的分区间距共存。先确定阅读和操作任务，而非先追求某个留白百分比：长列表需要稳定行节奏，决策表单需要保留说明和校验，空页面需要连贯的中心内容组，不能沿用满列表的 padding 就算完成。
 宽度变小时，先保留语义组，再考虑缩短文案或移动操作。以完整组为单位换行，组内间距模式保持稳定。高度增加时，明确哪个区域应该伸展，单靠固定 gap 无法定位空状态。同时检查过密和过疏：内容密集但便于比较可以成立，页面稀疏也可能分组混乱。
 <a id="hierarchy"></a>
 ## 4. 信息层级
 让下一步需要阅读或决定的信息可见，不必把每段文字都变成标题。
 强调必须表达与任务有关的差异。当前选择、可处理的错误和决策依据，需要稳定可辨；标签和补充信息可以更弱，但让有用的文字难以阅读不是层级设计。联合观察字号、字重、颜色、位置和周围留白；每个标题都把五种强调用满，反而失去有意义的区别。
 图标与文字的前景角色及语义例外由[图标专项](../.agents/skills/dsh-ui-icons/SKILL.md)负责；案例 C1 将该规则用于搜索框。
 字体也是几何的一部分：结合预期字体、长翻译与相关字体设置，比较文字起点、基线和行框。字号配套行高，并遵循[视觉基础](../.agents/skills/dsh-client-ui-ux/references/visual-foundation.md)的字重限制。正文、代码、终端与固定界面角色不必同幅缩放；把差异判为缺陷前，核对[字体设置所有方](../packages/client/ui-theme/README.zh.md)。先修容器分配，不用缩小有用文字来强行对齐。
 <a id="case-search-color"></a>
 ### 示例 C1：同一信息单元的图文强调
 **场景与关系。**比较空的自动化搜索框与展开的侧栏搜索框。二者都是放大镜配合提示文字，但一处图标更深，另一处文字更深。
 **修正与验收。**为空输入提示指定一个前景色角色，包含前导图标。联合检查计算后的颜色、透明度、禁用样式与背景；祖先单独淡化某个子元素时，相同 token 仍可能产生不同结果。检查空值、输入文字、焦点、禁用及明暗主题。已输入的查询文字和具有独立操作的清除按钮，不必使用较弱的占位提示色。
 <a id="states"></a>
 ## 5. 控件状态
 持续状态与临时反馈同时出现时，仍须能够区分。
 状态设计要赋予稳定含义，而不只是换几种颜色。选中表示“当前所在项”，悬停表示“指针在这里”，焦点表示“键盘输入作用于这里”，禁用表示“这个操作暂不可用”。同时比较叠加状态与相邻条目：选中行旁边出现另一条悬停行，与同一行的选中＋悬停同样重要。
 | 组合 | 必须继续可辨的含义 | 应寻找的错误 |
 |---|---|---|
 | 已选中＋另一行悬停 | 当前所在位置仍可识别 | 临时悬停行比当前行更像选中 |
 | 同一项已选中＋悬停 | 选中保留，同时有交互反馈 | 通用 hover 底色抹掉当前状态 |
 | 已选中＋键盘焦点 | 当前位置与键盘目标均可区分 | 焦点提示融进选中样式 |
 | 已选中＋禁用 | 保留的选择与暂不可用同时可辨 | 淡化后看起来像取消了选择 |
 | 展开＋菜单打开 | 当前操作有明确归属 | 面板高亮与行高亮无稳定关系地竞争 |
 <a id="case-sidebar-state"></a>
 ### 示例 S1：持续选中与临时悬停共存
 **场景与关系。**对照 master 基线检查当前会话、相邻悬停行和已打开的行菜单。背景绘制只是线索之一，还需结合当前行语义和浮现的操作；选中与悬停不必使用不同颜色。
 **修正与验收。**保留 master 的状态表达，确认悬停结束或菜单关闭后选中仍然保持。在相邻行之间移动指针并使用键盘遍历，同时检查焦点、操作可见性和当前行语义。不能仅为满足本案例而加深选中填充。比较相同主题与平台材质；不透明的隔离场景不能证明 Desktop 半透明背景的对比关系。
 <a id="component-choice"></a>
 ## 6. 组件选型
 先根据交互含义选择组件，再让布局适应可用空间。
 先按用户能做什么选择元素，再让并列元素保持视觉一致。导航打开目的地，开关改变设置，复选框添加独立选项，操作按钮启动动作；几何相似不代表可以互换。卡片增加了容纳内容的分组与空间，只有当该组需要独立摘要、状态或操作时才成立，不能仅因一行看起来朴素就改成卡片。
 标签、可见边界、焦点行为和点击区域应与交互含义一致。视觉修正若改变这些语义，还需检查行为。几何和圆角另见[第 8 节](#geometry)；“原生控件”既不保证视觉适配，也不是丢掉键盘与可访问行为的理由。
 <a id="icon-optics"></a>
 ## 7. 图标光学
 [图标 skill](../.agents/skills/dsh-ui-icons/SKILL.md)负责界面图标的角色、槽位、颜色和视觉平衡；[官方 artwork](../.agents/skills/dsh-official-plugin-artwork/SKILL.md)保留独立职责。
 <a id="case-file-optics"></a>
 ### 示例 O1：不同类型图标的光学对齐
 **场景与关系。**在同一树形深度比较关闭／打开的文件夹、原生文件类型图标、通用文件及无图标名称，再比较下一层的同样组合。
 **修正与验收。**保留层级缩进和共同文字起点，先统一放置槽，再比较槽内可见中心与视觉重量。不能移动文字去补偿单个 glyph，也不能把所有深度压到同一边缘。检查正常尺寸和放大图，包含选中底色与长文件名；放大图用于诊断绘制，正常尺寸决定结果是否平衡。
 <a id="geometry"></a>
 ## 8. 控件几何与圆角关系
 一致意味着相同角色、相同尺寸变体遵循同一规则，不同角色之间具有可理解的关系。联合检查外部高度、宽度、圆角、曲线、内缩与可见底板。合法 token 也能组合出不协调的外观，所有元素套用同一个圆角同样可能不协调。数值与嵌套几何由[圆角规范](ui-radius.zh.md)拥有，本文不另建尺度。
 区分沿容器内缩的贴合表面与面板里的独立卡片：前者要协调内外曲线和内缩距离，后者按自身组件角色选择。一起检查底色、描边、高亮、伪元素与裁切。即使静止描边正确，hover 底色改变了可见轮廓，也属于状态缺陷。
 ### 按这个顺序判断几何
 先确定语义角色，选择已有尺寸变体，识别父子关系，再观察曲线、材质和状态。[圆角尺度](ui-radius.zh.md#radius-scale)及其明确例外提供数值；展开后的外接框变大，不会自动选择新档位。相同半径数值也可能因高度或曲线不同而产生不同观感。
 | 关系 | 从圆角所有方得到的判断 | 要寻找的视觉错误 |
 |---|---|---|
 | 圆弧同心内缩 | 内半径为外半径减内缩，最小为零；圆弧共用圆心 | 内外同半径使可见间隔在角落挤压或扩大 |
 | 嵌套超椭圆 | 采用共享名义尺寸关系，再观察斜向留白；它们不是严格偏移曲线 | 仅凭半径相减就声称数学上等距 |
 | 贴边填色或相邻分段 | 外框拥有暴露角落，内部接缝保持方角 | 缺口、月牙、双轮廓，或焦点被随底色一起裁掉 |
 | 独立子卡片／分组 | 按自身角色选档，不机械减去全部周围空间 | 因父级 padding 很大而把合理子圆角减成零 |
 | 明确的圆形／胶囊 | 容器与实际绘制内容保持圆弧 | 圆形头像容器里嵌着非圆形图片；胶囊端部变方圆 |
 在整页或整个弹窗中一起比较底色、描边、hover 覆盖层、焦点和裁切。平面卡片边框与有层级阴影的材质，在 [Web 样式](web-styling.zh.md#component-rules)中具有不同绘制归属，同时应用可能让边缘加倍。轮廓裁切底色时，弹出菜单和键盘焦点仍须完整可见。几何与持续使用应一起判断。
 #### Fluent：分段按钮的缺口是关系错误
 [Shapes 案例](https://fluent2.microsoft.design/shapes/#when-to-avoid-rounded-corners)标出了两个各自圆角的按钮半区相接时形成的空隙。应观察内部接缝而非外部四角：把每半区都当成独立完整轮廓，会破坏共同外框。这是具体的反例，不是在建议所有控件都更圆。
 [![Fluent 反例：两个全圆角半区造成内部缺口](https://fluent2.microsoft.design/_image?f=png&h=440&href=https%3A%2F%2Ffluent2websitecdn.azureedge.net%2Fcdn%2Fdesignlanguage-shapes-cornerradius-03.D70MlS4K.webp&w=728)](https://fluent2.microsoft.design/shapes/)
 图片来自 Microsoft Fluent 2，链接到原始来源。在 DSH 中采用圆角规范的贴边填色关系，再一起检查左右两半的悬停、焦点和弹出菜单是否完整显示。Fluent 的圆角与描边尺度不是 DSH 默认值。观察内部接缝的凹口；原图是反例，不是 DSH 的修改前后对照。
 <a id="case-model-radius"></a>
 ### 示例 R1：不同层级容器与控件的圆角
 **场景与关系。**模型编辑器包含模型分组行、每行两个输入框、“添加模型”按钮及取消／保存操作。这些圆角同时出现在一屏，角色和尺寸关系必须能够一起读懂。
 **修正与验收。**先区分外层编辑器、模型组、字段、按钮，再选择现有变体。同角色同尺寸控件保持一致，紧密嵌套曲线与实际内缩距离协调，独立子控件保留自己的角色。检查行的折叠／展开、字段焦点、hover 底色及长模型名，不能拿展开后的总高度解释任意圆角。
 <a id="case-checkbox-radius"></a>
 ### 示例 R2：表单中小型选择控件的轮廓
 **场景与关系。**输入类型选项使用深色原生复选框，旁边是圆角表单控件。这里检查小型选择控件的外轮廓和重量，不是要求复选框具有大输入框的圆角。
 **修正与验收。**采用协调的小型选择控件样式，保留复选框易辨识的轮廓及标签关联。替换原生外观时，继续保留选中／未选中、禁用、键盘焦点和辅助技术语义。明暗主题中按实际尺寸比较这些状态；未选中的线框与选中的底色必须属于同一控件族。
 <a id="case-automation-radius"></a>
 ### 示例 R3：不同角色之间有依据的几何差异
 **场景与关系。**自动化页相邻的筛选项、搜索框和主创建操作采用不同圆角。即使高度接近，各功能自己选择半径，仍可能产生明显的弯曲感跳变。
 **修正与验收。**复用已有控件变体，真正的胶囊是明确的组件类型，不代表所有紧凑按钮都应使用高度一半作为半径。将筛选、搜索和主次按钮放在同一画面比较，同时检查 hover 与焦点轮廓。预期的胶囊／字段差异可以保留，不能仅因同行就强制圆角相等。
 <a id="reproduce"></a>
 ## 复现与比较
 本地维护的生产组件 fixture 可提供固定内容与状态的隔离示例。实际应用截图应来自本次要审查的整页或整个弹窗，包含相关区域与状态。fixture 只能证明它所渲染的条件，不能决定或完成审查范围。
 这些组件中的尺寸是对应案例的证据，不是通用设计常数。共享数值仍由[样式参考](web-styling.zh.md)、[圆角标准](ui-radius.zh.md)及组件归属方定义。新增使用位置或任务不同时，应补充证据，不能脱离条件照抄案例数值。
 <a id="references"></a>
 ## 外部参考与 DSH 的取舍
 这些是研究输入，不是自动启用的 skill，也不替代 DSH 规范。下列材料阅读于 2026-10-26。公开资料提供比较方法，本文 DSH 案例和原理图是结合本地场景的归纳；链接指向原作者。使用本文不需要安装或执行外部 skill。
 | 参考 | 可采用的贡献 | 范围与明确取舍 |
 |---|---|---|
 | [Anthropic frontend-design](https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md) | 明确构图、围绕实际内容做选择、观察渲染结果自评 | 表现性视觉方向不意味着应重设工作界面风格或更换 DSH 字体 |
 | [Vercel web-design-guidelines skill](https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md) 与[规则](https://github.com/vercel-labs/web-interface-guidelines/blob/main/command.md) | 定位问题源码，覆盖焦点、标签、长内容与交互 | 代码合规不能证明对齐和分组；其 title case 建议不覆盖 DSH 的 sentence case |
 | [Impeccable](https://github.com/pbakaus/impeccable/blob/main/.agents/skills/impeccable/SKILL.md)、[critique](https://github.com/pbakaus/impeccable/blob/main/.agents/skills/impeccable/reference/critique.md)、[polish](https://github.com/pbakaus/impeccable/blob/main/.agents/skills/impeccable/reference/polish.md)、[operate](https://github.com/pbakaus/impeccable/blob/main/.agents/skills/impeccable/reference/operate.md) | 区分任务型界面与宣传设计，区分视觉判断与检测器输出 | 采用完整路径检查与现有系统比较，不引入其执行、委派或评分机制 |
 | [Interface Design](https://github.com/Dammyjay93/interface-design/blob/main/.claude/skills/interface-design/SKILL.md) | 明确产品意图、复用重复模式、与已有相邻界面比较 | 保留 DSH 现有系统，不照搬示例字重、不另建 token 目录、不为独特而独特 |
 | [OpenAI figma-implement-design](https://github.com/openai/skills/blob/main/skills/.curated/figma-implement-design/SKILL.md) | 用真实视觉参考比较渲染结果，并整合已有组件 | 截图是有范围的证据，不代表可以推断未展示状态或照搬每个数值 |
 | [Fluent Shapes](https://fluent2.microsoft.design/shapes/)与 [Primer Forms](https://primer.style/product/ui-patterns/forms/) | 能直接检查关系的组件反例 | 上文案例分析迁移判断方法，不迁移其 token 或交互体系 |
 | [Atlassian spacing](https://atlassian.design/foundations/spacing/) | 邻近关系、重复节奏、层级与光学调整的正反例 | 借鉴关系判断，不移植 Atlassian token 名称或自动像素公式 |
 | [Carbon spacing](https://www.carbondesignsystem.com/building-blocks/foundations/spacing/overview) | 间距模式表达等权与分区边界，流式居中不同于固定距离 | 沿用 DSH 间距所有方，只有一套尺度仍不能选择正确分组关系 |
 | [Codex 官方产品介绍](https://openai.com/index/introducing-the-codex-app/)与[桌面文档](https://learn.chatgpt.com/docs/app) | 任务导向的构图和可比较的真实公开示例 | 公开示例是特定版本的观察，不是当前本机应用或未公开的 Codex 设计规范 |
 ### Codex：限定用途的构图参照
 官方[欢迎区／输入框封面](https://learn.chatgpt.com/images/codex/video-posters/proactive-teammate-v2.webp)与[长输入封面](https://learn.chatgpt.com/images/codex/video-posters/draft-prds-from-slack-linear-docs.webp)展示居中的介绍内容、居左的输入文字，以及底部独立控件组，可以支持这项构图比较。它们没有展示完整侧栏对齐、嵌套圆角、相邻选中／悬停或缩放变化。这些判断应使用上文更具体的案例，不能把产品封面当作广泛设计背书。
 外部图片保留在署名来源中。源图不可用时，邻近分析仍指出比较对象；新审查要使用该图作视觉证据前，应先取得可用参照。
 <a id="dev-note"></a>
 ## 开发备注
 无。
@@ -24,8 +24,8 @@
  en: 7fe4eb7707e6a9f3
  zh: be7530a05c205e27
 /dsh-unified-corner-radius-standard/settings-card-materials:
-  en: 85e7e63183df06d1
+  en: 126066f9c638433c
-  zh: 1da2b44083d7ebe2
+  zh: a7416d255f838b92
 /dsh-unified-corner-radius-standard/apply-and-verify:
  en: 2f6f10e45b27c19b
  zh: 9eb5fd964c643be6
@@ -107,6 +107,8 @@ The theme resolves the card fill to `--dsw-alias-bg-layer-2` and the stroke to `
 Flat neutral borders use the shared 0.5px hairline. Elevated menus, popovers, dialogs, and panels use `border: 0` with the existing `--dsw-elevation-*` material, whose shadow includes the hairline. Do not add a second neutral border over that stroke or add a shadow to an ordinary settings card merely to distinguish its tab. Preserve semantic state-colored borders and the existing translucent-menu backdrop behavior.
 A page-level radius review compares roles and silhouettes together, including native small selection controls. Token compliance only establishes membership in the scale; it does not establish that adjacent roles or nested contours look coherent. Use the [geometry cases](ui-design-review-cases.md#geometry) for the comparison method, while this document remains the owner of values and curve rules.
 <a id="verification"></a>
 ## Apply and verify
@@ -107,6 +107,8 @@ H 表示以 CSS 像素计、包含边框的设计外部高度。R 表示浏览
 平面中性边框使用共享的 0.5px 发丝线。具有层级阴影的菜单、浮层、对话框和面板使用 `border: 0` 与既有 `--dsw-elevation-*` 材质，其阴影已包含发丝描边。不要在该描边上再叠一层中性边框，也不要仅为区分设置 tab 就给普通设置卡片加阴影。保留语义状态色边框与既有的半透明菜单背景效果。
 整页圆角审查要同时比较角色与轮廓，包含原生的小型选择控件。符合 token 只能证明数值属于尺度，不能证明相邻角色或嵌套轮廓协调。比较方法见[几何案例](ui-design-review-cases.zh.md#geometry)，本规范继续拥有数值与曲线规则。
 <a id="verification"></a>
 ## 应用与验证
@@ -17,6 +17,9 @@
 /web-ui-style-reference/corner-radii-and-settings-cards:
  en: 118972f6c2bd6ce4
  zh: 85f8416b03e4dd8b
 /web-ui-style-reference/review-the-assembled-design:
  en: 21bed565fa27b823
  zh: 84b5a96127c842c0
 /web-ui-style-reference/changing-the-system:
  en: 71501119492a3ad4
  zh: 87bf6c9406d0d9ed
@@ -46,6 +46,10 @@ On a mixed-input device, a mouse preview can appear while the primary-pointer CS
 The [DSH unified corner-radius standard](ui-radius.md) defines the radius scale, component size mapping, circle and capsule exceptions, nested hover geometry, and settings-card fills and strokes.
 ## Review the assembled design
 Use the [UI review baseline](ui-design-review-cases.md#review-baseline) to combine these material and typography rules with radius, responsive behavior, feedback and artwork guidance across the [entire page or modal](ui-design-review-cases.md#whole-interface-review). Compare all regions and same-role elements within that unit; individually compliant components can still form doubled edges, inconsistent grouping or clipped focus indicators. This document and the theme remain the styling owners.
 ## Changing the system
 Add or change a shared token in the owning `ui-theme` sheet, then consume its semantic alias from feature packages. Update the owning package reference when a public styling contract changes. Visual behavior follows the [testing policy](testing.md); the [archived styling-system Agent Note](../.agents/notes/archived/process/2026-07-19-web-styling-system.md) records framework rationale.
@@ -46,6 +46,10 @@
 圆角尺度、组件尺寸映射、正圆与胶囊例外、嵌套 hover，以及设置卡片的底色与描边统一由 [DSH 统一圆角规范](ui-radius.zh.md)定义。
 ## 审查组装后的设计
 按 [UI review 基准](ui-design-review-cases.zh.md#review-baseline)，在[整页或整个弹窗](ui-design-review-cases.zh.md#whole-interface-review)中综合判断材质、字体、圆角、响应式行为、反馈和图案。统一比较这个范围内的所有区域与同角色元素；组件分别合规，组合后仍可能出现双描边、分组不一致或焦点被裁切。本规范与主题继续拥有样式规则。
 ## 变更系统
 在所属 `ui-theme` 样式表中添加或修改共享 token，然后在功能包中使用其语义别名。公共样式约定发生变化时，更新所属包的参考文档。视觉行为遵循[测试策略](testing.zh.md)；[已归档的样式系统 Agent Note](../.agents/notes/archived/process/2026-07-19-web-styling-system.md) 记录框架依据。
@@ -115,6 +115,8 @@ One UI feature = one plugin package (`src/client/` browser half). A multi-domain
 ## Styling and localization
 For the required UI review, trace affected assembled pages and shared-component consumers; file ownership does not bound visual impact. Use the [scope selection](../../docs/cookbook/reviewing-ui-design.md#review-scope) before editing, and the [completion criteria](../../.agents/skills/dsh-client-ui-ux/SKILL.md#required-review-loop) before handoff.
 [docs/web-styling.md](../../docs/web-styling.md) is authoritative. Shared `--dsw-*` tokens and global sheets live in `ui-theme/src/styles/`; feature components consume semantic aliases through CSS Modules and `clsx`, with no literal colors, component library, or Tailwind. Code comments are English. Design judgment beyond those rules — feedback surfaces, loading states, overlay safety, platform window adaptation — follows [dsh-client-ui-ux](../../.agents/skills/dsh-client-ui-ux/SKILL.md); responsive layout and telling a mobile or touch client from a desktop one follow [dsh-responsive-ui](../../.agents/skills/dsh-responsive-ui/SKILL.md).
 Menus use `Menu` or `MenuSurface`, including custom listboxes, except the explicitly listed schedule containers. Preserve the shared transparency and blur ([rules](../../docs/web-styling.md#component-rules)).