mirror of
https://github.com/deepseek-ai/deepseek-harness.git
synced 2026-11-09 20:07:43 +08:00
docs: consolidate UI skill rules and geometry guidance
This commit is contained in:
yixiangihsiang
@@ -5,14 +5,14 @@ description: Use before implementing any DSH user-visible UI change and during U
|
||||
|
||||
# DeepSeek Harness UI development
|
||||
|
||||
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.
|
||||
Use this entry before changing UI. It owns the development workflow, visual foundation, component geometry, and interaction guidance; linked owners supply specialized design rules. 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.
|
||||
|
||||
## Required review loop
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
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.
|
||||
2. **Implement using those decisions.** Reuse the selected components and existing values. Check group structure and shared axes before optical detail. 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.
|
||||
|
||||
@@ -27,9 +27,9 @@ For layout and grouping changes, read alignment and spacing directly before posi
|
||||
| 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 |
|
||||
| Color, typography and existing treatments | [Visual foundation](#visual-foundation); [Web styling](../../../docs/web-styling.md) owns tokens/materials |
|
||||
| Component geometry, nested contours and state fills | [Geometry decisions](#component-geometry); [radius standard](../../../docs/ui-radius.md) owns values and exceptions |
|
||||
| Feedback lifetime, loading, overlays, scrolling and platform clearance | [Interaction and feedback](#interaction-and-feedback); [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) |
|
||||
@@ -41,6 +41,59 @@ Extend the existing component, container or interaction when the new capability
|
||||
|
||||
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.
|
||||
|
||||
## 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.
|
||||
|
||||
## Component geometry
|
||||
|
||||
Choose the component's role, reuse its size variant, then identify how it relates to its container. Compare height, radius, curve, inset and visible material together. Equal radius values alone do not make neighboring controls coherent; wrapping or expansion alone does not select a larger radius. Use the [radius scale and component exceptions](../../../docs/ui-radius.md#radius-scale) for actual values.
|
||||
|
||||
- **Inset surface:** coordinate the inner curve with the outer curve and inset. Radius subtraction gives concentric circular arcs; for superellipses it is a nominal sizing rule, so inspect diagonal whitespace as well as the side gap.
|
||||
- **Flush fill or adjoining segments:** let the enclosing surface own exposed corners and keep internal joins square. Hover fills and pseudo-elements follow that contour. Keep menus outside clipping and retain visible keyboard focus.
|
||||
- **Independent child card or form group:** choose its own role and size tier. Do not subtract all parent padding or give it the enclosing dialog's radius.
|
||||
- **Circles and capsules:** preserve their intended shape, including both an avatar container and its image. Follow the theme's round-curve exception; ordinary controls use the shared curve.
|
||||
|
||||
Keep geometry stable across hover, pressed, selected, loading and disabled states. Compare fills, strokes and overlays with the same silhouette. Use the existing [card and elevation materials](../../../docs/ui-radius.md#settings-cards); an elevation shadow already includes its neutral hairline, so adding another border doubles the edge. Preserve semantic state-colored borders.
|
||||
|
||||
Inspect related controls together at actual size, including small selection controls, in the affected themes and states. Check longer labels and narrow layouts when they change the composition. Existing radius, curve and elevation checks catch unsupported declarations; rendered comparison establishes whether the chosen values fit. The [geometry cases](../../../docs/ui-design-review-cases.md#geometry) illustrate this judgment. These decisions guide changes in scope; they do not call for a bulk restyling of existing components.
|
||||
|
||||
## 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.
|
||||
|
||||
## Check the rules together
|
||||
|
||||
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.
|
||||
|
||||
@@ -1,31 +0,0 @@
|
||||
# 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.
|
||||
@@ -1,7 +0,0 @@
|
||||
# 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.
|
||||
@@ -32,13 +32,7 @@ Specify what is aligning to what. Distinguish the element's layout box, its visi
|
||||
|
||||
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.
|
||||
Consider 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.
|
||||
|
||||
|
||||
@@ -21,9 +21,6 @@ As a group gains subgroups, wrapping, secondary metadata, or independent operati
|
||||
|
||||
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.
|
||||
|
||||
@@ -9,8 +9,8 @@
|
||||
en: d42b121ca63177aa
|
||||
zh: 68b637fae3252c7b
|
||||
/cookbook-review-a-ui-design/summary:
|
||||
en: e1512525090123b8
|
||||
zh: 4a6749841c93917b
|
||||
en: fbacaf1923ae317d
|
||||
zh: d22ac1df97fbfb6e
|
||||
/cookbook-review-a-ui-design/table-of-contents:
|
||||
en: 84af073b2a7eca95
|
||||
zh: 750633fa3c458d5b
|
||||
|
||||
@@ -12,8 +12,6 @@ Use this workflow for impact-scoped UI changes and explicitly requested whole-in
|
||||
|
||||
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)
|
||||
|
||||
@@ -12,8 +12,6 @@ description: "把 DSH 页面或弹窗作为整体审查，按设计原则说明
|
||||
|
||||
对齐审查先核对图标完整空间（含有意保留的内部留白）、文字列和间距，再检查实际轮廓。热区不等于图标框；不逐个拉齐 glyph 的像素边缘。判断顺序见[对齐原则](../ui-design-review-cases.zh.md#alignment)。
|
||||
|
||||
侧栏审查记录当前 master 版本，并遵循[侧栏设计基线](../../.agents/skills/dsh-ui-alignment/SKILL.md#sidebar-design-baseline)。先保留相关角色与状态的基线，再比较工作版本。旧示意图和报告不能证明当前布局，也不能作为恢复已被取代的几何关系的理由。
|
||||
|
||||
## 目录
|
||||
|
||||
- [1. 确定受审页面或弹窗](#proposition)
|
||||
|
||||
@@ -39,17 +39,17 @@
|
||||
en: 1ff7bb879b274363
|
||||
zh: 4659578bcdea82a3
|
||||
/ui-design-principles-and-review-cases/1-alignment:
|
||||
en: 7f814736464f0d76
|
||||
zh: f2aad824c15a6ca3
|
||||
en: 31d18363696173e9
|
||||
zh: d2bbca62e7ea0120
|
||||
/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
|
||||
en: 593b824ab3fc6474
|
||||
zh: 19692388cdf7da7d
|
||||
/ui-design-principles-and-review-cases/1-alignment/example-a2-distinct-header-and-row-action-groups:
|
||||
en: 5067e586053db8d5
|
||||
zh: 153168b1016950d1
|
||||
en: 81d165cc1c5c1f7e
|
||||
zh: 4aef022e141ced64
|
||||
/ui-design-principles-and-review-cases/1-alignment/example-a3-alignment-between-rows-and-compound-controls:
|
||||
en: 0f387b953c8c3e34
|
||||
zh: 5362d3467a65ec59
|
||||
@@ -78,8 +78,8 @@
|
||||
en: 9d7e04a0314ac527
|
||||
zh: fc654332df43d0c1
|
||||
/ui-design-principles-and-review-cases/2-spatial-grouping/example-g4-separating-groups-with-different-purposes:
|
||||
en: 0e4b070c7bd088a1
|
||||
zh: 736b5978d42a7c55
|
||||
en: 77bc7ec83d75ff29
|
||||
zh: caab9079ae3e416a
|
||||
/ui-design-principles-and-review-cases/2-spatial-grouping/composed-whitespace-and-responsive-grouping:
|
||||
en: 47f8ea920c78c5be
|
||||
zh: e64ab054666c3727
|
||||
@@ -87,8 +87,8 @@
|
||||
en: 10fb29eddaac1951
|
||||
zh: e05636b47e860966
|
||||
/ui-design-principles-and-review-cases/4-information-hierarchy:
|
||||
en: 7defd0a4ca8d2c07
|
||||
zh: 7911c63ad109aeb9
|
||||
en: 56ecb557d54c1c2e
|
||||
zh: ede48f8451af4111
|
||||
/ui-design-principles-and-review-cases/4-information-hierarchy/example-c1-color-emphasis-within-one-information-unit:
|
||||
en: ae07e8886d00c5bb
|
||||
zh: 1229ab4ae6394c0b
|
||||
@@ -96,8 +96,8 @@
|
||||
en: d247699132b484a0
|
||||
zh: b71e25d834ce2633
|
||||
/ui-design-principles-and-review-cases/5-control-states/example-s1-persistent-selection-beside-temporary-hover:
|
||||
en: e6c650517a1e938c
|
||||
zh: 0aa7f8f2e8bd22c3
|
||||
en: 729e11936e471a67
|
||||
zh: d1da0c090e78efb5
|
||||
/ui-design-principles-and-review-cases/6-component-choice:
|
||||
en: 7a49fdd5a601aa48
|
||||
zh: e2f9de0d5628a878
|
||||
|
||||
@@ -137,7 +137,7 @@ The [alignment skill](../.agents/skills/dsh-ui-alignment/SKILL.md) owns shared a
|
||||
|
||||
|
||||
|
||||
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.
|
||||
The schematic distinguishes peer-row axes from account and header geometry; it is not a pixel specification. Compare content, painted backgrounds and hit targets separately; different roles need not share every axis.
|
||||
|
||||
### Text metrics and unequal content
|
||||
|
||||
@@ -156,18 +156,18 @@ The comparison below shows actual preset cards with unequal descriptions. On the
|
||||
<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.
|
||||
**Scene and relationship.** Compare navigation, workspace rows, conversations and the account area in the expanded sidebar. 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.
|
||||
**Acceptance.** Use guides to compare same-role rows. 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.
|
||||
**Failure and correction.** Choose control sizes, gaps and trailing insets by group role, including during search expansion. 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.
|
||||
|
||||
@@ -253,7 +253,7 @@ Image: IBM Carbon Design System. Follow the annotations between the introduction
|
||||
|
||||
**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.
|
||||
**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; compare the 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
|
||||
|
||||
@@ -285,7 +285,7 @@ Use emphasis to express a task-relevant difference. A current selection, an acti
|
||||
|
||||
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.
|
||||
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/SKILL.md#visual-foundation). 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
|
||||
@@ -312,9 +312,9 @@ State design assigns stable meanings, not just different colors. Selection says
|
||||
<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.
|
||||
**Scene and relationship.** Compare the selected conversation, a neighboring hovered row and an open row menu. 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.
|
||||
**Correction and acceptance.** 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. Compare the same theme and platform material; an opaque fixture cannot establish translucent Desktop contrast.
|
||||
|
||||
<a id="component-choice"></a>
|
||||
## 6. Component choice
|
||||
|
||||
@@ -137,7 +137,7 @@ DSH 的视觉审查优先关注对齐与空间分组。先识别任务和语义
|
||||
|
||||
|
||||
|
||||
示意图区分同类行的轴线与账号、标题区域的几何关系，不是像素规范。[侧栏基线](../.agents/skills/dsh-ui-alignment/SKILL.md#sidebar-design-baseline)负责当前关系。分别比较内容、背景绘制区域和点击区域；不同角色不必共用所有轴线。
|
||||
示意图区分同类行的轴线与账号、标题区域的几何关系，不是像素规范。分别比较内容、背景绘制区域和点击区域；不同角色不必共用所有轴线。
|
||||
|
||||
### 文字度量与不等长内容
|
||||
|
||||
@@ -156,18 +156,18 @@ DSH 的视觉审查优先关注对齐与空间分组。先识别任务和语义
|
||||
<a id="case-sidebar-axes"></a>
|
||||
### 示例 A1：按角色判断侧栏对齐
|
||||
|
||||
**场景与关系。**对照已记录的 master 基线，比较展开侧栏中的导航、工作区行、会话和账号区域。检查居中的新会话操作与行背景边缘，而不只比较文字起点。
|
||||
**场景与关系。**比较展开侧栏中的导航、工作区行、会话和账号区域。检查居中的新会话操作与行背景边缘，而不只比较文字起点。
|
||||
|
||||
**错误与修正。**为所有角色套用同一前导槽宽度，会移动标题、拉大间距或改变已登录账号行。保留所属组件的共享变量、紧凑图标槽和绘制内缩。保留有意设计的账号几何关系与层级，不强造贯穿所有角色的文字轴。
|
||||
|
||||
**验收。**只为基线已建立的关系绘制辅助线。检查长短标题、可选图标、项目展开和账号登录／未登录状态。行操作浮现不能移动标题起点。列表裁图不能证明完整侧栏对齐。
|
||||
**验收。**用辅助线比较同角色的行。检查长短标题、可选图标、项目展开和账号登录／未登录状态。行操作浮现不能移动标题起点。列表裁图不能证明完整侧栏对齐。
|
||||
|
||||
<a id="case-action-columns"></a>
|
||||
### 示例 A2：区分标题操作与行操作
|
||||
|
||||
**场景与关系。**工作区的搜索／筛选／添加与会话的更多／归档／置顶都处于侧栏尾部，但角色和间距不同。重复行之间互相比较；标题区域则比较自身搜索收起和展开的状态。
|
||||
|
||||
**错误与修正。**强迫两组共用三槽网格会改变 master 设计。保留各组的控件尺寸、间距、尾部内缩与搜索过渡。标题到操作组的分隔独立于组内间距。
|
||||
**错误与修正。**按各组角色选择控件尺寸、间距与尾部内缩，并检查搜索展开时的布局。标题到操作组的分隔独立于组内间距。
|
||||
|
||||
**验收。**同时显示标题与行操作，再展开搜索并折叠侧栏。检查预期边缘关系、未裁切的点击区域和长标题避让。不能为了让无关控件形成垂直列而补空操作或偏移。
|
||||
|
||||
@@ -253,7 +253,7 @@ DSH 的视觉审查优先关注对齐与空间分组。先识别任务和语义
|
||||
|
||||
**场景与关系。**“新会话”是主操作，插件／自动化／更多组成全局导航，工作区标题介绍项目列表。相同行高不能表达这几种不同关系。
|
||||
|
||||
**修正与验收。**导航行彼此靠近，导航组与工作区分开，工作区标题更靠近它所标注的项目，主操作与导航组保留独立间隔。连同账号区域检查完整侧栏；保留基线间距及 A1 按角色区分的关系。在每个项目前都增加大间距，会错误地把每个项目变成独立分区。
|
||||
**修正与验收。**导航行彼此靠近，导航组与工作区分开，工作区标题更靠近它所标注的项目，主操作与导航组保留独立间隔。连同账号区域检查完整侧栏；比较 A1 按角色区分的关系。在每个项目前都增加大间距，会错误地把每个项目变成独立分区。
|
||||
|
||||
### 组合后的留白与响应式分组
|
||||
|
||||
@@ -285,7 +285,7 @@ DSH 的视觉审查优先关注对齐与空间分组。先识别任务和语义
|
||||
|
||||
图标与文字的前景角色及语义例外由[图标专项](../.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)。先修容器分配，不用缩小有用文字来强行对齐。
|
||||
字体也是几何的一部分：结合预期字体、长翻译与相关字体设置，比较文字起点、基线和行框。字号配套行高，并遵循[视觉基础](../.agents/skills/dsh-client-ui-ux/SKILL.md#visual-foundation)的字重限制。正文、代码、终端与固定界面角色不必同幅缩放；把差异判为缺陷前，核对[字体设置所有方](../packages/client/ui-theme/README.zh.md)。先修容器分配，不用缩小有用文字来强行对齐。
|
||||
|
||||
<a id="case-search-color"></a>
|
||||
### 示例 C1：同一信息单元的图文强调
|
||||
@@ -312,9 +312,9 @@ DSH 的视觉审查优先关注对齐与空间分组。先识别任务和语义
|
||||
<a id="case-sidebar-state"></a>
|
||||
### 示例 S1：持续选中与临时悬停共存
|
||||
|
||||
**场景与关系。**对照 master 基线检查当前会话、相邻悬停行和已打开的行菜单。背景绘制只是线索之一，还需结合当前行语义和浮现的操作；选中与悬停不必使用不同颜色。
|
||||
**场景与关系。**比较当前会话、相邻悬停行和已打开的行菜单。背景绘制只是线索之一，还需结合当前行语义和浮现的操作；选中与悬停不必使用不同颜色。
|
||||
|
||||
**修正与验收。**保留 master 的状态表达，确认悬停结束或菜单关闭后选中仍然保持。在相邻行之间移动指针并使用键盘遍历，同时检查焦点、操作可见性和当前行语义。不能仅为满足本案例而加深选中填充。比较相同主题与平台材质；不透明的隔离场景不能证明 Desktop 半透明背景的对比关系。
|
||||
**修正与验收。**确认悬停结束或菜单关闭后选中仍然保持。在相邻行之间移动指针并使用键盘遍历，同时检查焦点、操作可见性和当前行语义。比较相同主题与平台材质；不透明的隔离场景不能证明 Desktop 半透明背景的对比关系。
|
||||
|
||||
<a id="component-choice"></a>
|
||||
## 6. 组件选型
|
||||
|
||||
@@ -12,8 +12,8 @@
|
||||
en: aad65e4a8399adbb
|
||||
zh: e76b80d421b17992
|
||||
/dsh-unified-corner-radius-standard/scope-and-authority:
|
||||
en: cd8120cba5566e19
|
||||
zh: 65359436088c8bc5
|
||||
en: 909c1c11ccf420dc
|
||||
zh: 23bec3e3dfa856b6
|
||||
/dsh-unified-corner-radius-standard/select-the-radius:
|
||||
en: e736416ec85d6e16
|
||||
zh: 0edf60fccc867295
|
||||
|
||||
+1
-1
@@ -18,7 +18,7 @@ Choose consistent corner radii by component role and size, and align nested regi
|
||||
<a id="scope"></a>
|
||||
## Scope and authority
|
||||
|
||||
This reference defines the DSH Web and Desktop radius scale and its component rules. A local visual adjustment stays scoped to the named component or family and does not automatically change the global scale.
|
||||
This reference defines the DSH Web and Desktop radius scale, curve rules and component exceptions. Use the [UI design skill's geometry decisions](../.agents/skills/dsh-client-ui-ux/SKILL.md#component-geometry) to select and review their application. A local visual adjustment stays scoped to the named component or family and does not automatically change the global scale.
|
||||
|
||||
The [Web UI style reference](web-styling.md) defines general styling ownership. Shared values live in [`base.css`](../packages/client/ui-theme/src/styles/base.css), and curve behavior lives in [`corner-shape.css`](../packages/client/ui-theme/src/styles/corner-shape.css). Update the theme implementation and both language versions of this standard together when changing a rule.
|
||||
|
||||
|
||||
@@ -18,7 +18,7 @@
|
||||
<a id="scope"></a>
|
||||
## 范围与依据
|
||||
|
||||
本参考文档规定 DSH Web 和 Desktop 的圆角尺度及组件应用规则。局部视觉调整限定在指定组件或组件族内，不自动改变全局尺度。
|
||||
本参考文档规定 DSH Web 和 Desktop 的圆角尺度、曲线规则及组件例外。应用时按 [UI 设计 skill 的几何判断](../.agents/skills/dsh-client-ui-ux/SKILL.md#component-geometry)选择并审查。局部视觉调整限定在指定组件或组件族内，不自动改变全局尺度。
|
||||
|
||||
通用样式职责见 [Web UI 样式参考](web-styling.zh.md)。共享数值位于 [`base.css`](../packages/client/ui-theme/src/styles/base.css)，曲线行为位于 [`corner-shape.css`](../packages/client/ui-theme/src/styles/corner-shape.css)。修改规则时同步更新主题实现及本规范的中英文版本。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user