diff --git a/.agents/skills/dsh-client-ui-ux/SKILL.md b/.agents/skills/dsh-client-ui-ux/SKILL.md index 22b5182c83..104157c187 100644 --- a/.agents/skills/dsh-client-ui-ux/SKILL.md +++ b/.agents/skills/dsh-client-ui-ux/SKILL.md @@ -1,26 +1,26 @@ --- name: dsh-client-ui-ux -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. +description: Use before DSH user-visible UI changes and during UI review in client, experimental and app packages. Select design rules before coding and verify affected rendered results before handoff. --- # DeepSeek Harness UI development -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. +This entry owns the UI workflow, visual foundation, geometry and interaction guidance. Apply it to the task, not as an exhaustive checklist. Linked owners define specialized rules and values; examples explain judgment, not 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. +Layout, copy, icons, styling and interaction changes trigger this loop. Behavior edits include affected loading, error, disabled, expanded and focus states. Documentation-only edits and refactors with evidence of unchanged rendering need no 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. 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. +1. **Decide before coding.** Record the task, affected pages/modals, groups, axes, spacing, components and planned evidence in a few task-note sentences. Read applicable owners and select [affected states and consumers](../../../docs/cookbook/reviewing-ui-design.md#review-scope). Preserve starting source and images, including uncommitted UI; new UI may use an honestly labeled sketch or established sibling. +2. **Implement.** Reuse components and values; resolve structure and axes before optical detail. Expand scope for affected shared consumers, neighbors or states. Batch coherent edits before recapturing, without auditing the whole product per CSS change. +3. **Inspect the final render.** Check affected relationships and behavior in the assembled page/modal, retain comparable before/after evidence for position changes and run relevant checks. Report inspected, equivalent-by-evidence, unresolved and uninspected scope. Missing scenes, defects or failed checks block complete-validation claims; state gaps and next verification. +4. **Reconcile before PR/push.** Check cumulative interactions and coverage. Reuse evidence while source, dependencies, content, states and capture conditions remain valid; rerun only missing or invalidated checks. Deliver scope, decisions, evidence, results and gaps. -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. +Keep records in the task/local artifacts, not tracked checklists per edit. Read unchanged owners once and examples only for uncertain decisions. Select conditions by risk, not every width × theme × state or fixed screenshot counts. The [cookbook](../../../docs/cookbook/reviewing-ui-design.md) owns evidence procedures; tool success does not establish visual quality. ## Select the rule owners -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. +Read alignment and spacing before layout changes; otherwise select the applicable owners. Preserve existing relationships and keep each numeric scale with its owner. | Decision needed before implementation | Owner | |---|---| @@ -37,73 +37,64 @@ For layout and grouping changes, read alignment and spacing directly before posi ## Reuse before adding -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. - -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. +Extend existing components, containers and interactions when the capability fits. Register right-sidebar content in the existing sidebar. Follow [icon reuse](../dsh-ui-icons/SKILL.md#reuse-existing-icons-first). Before restructuring, read [client instructions](../../../packages/client/AGENTS.md) and [client defensive patterns](../../../docs/defensive-patterns/client-components.md) for component/state ownership and layering. ## 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. +- Reuse tokens, values and complete treatments from the target page or nearest established sibling before adding literals; Plugins is the usual full-page reference. +- Verify colors in light and dark themes; keep ink/background pairs readable, especially dimmed text. +- Feature CSS you add or change uses **font weight ≤500**; emphasize with size or ink. ui-theme markdown typography tokens are the exception. +- Use theme typography roles, then the page's scale, then a comparable page's size/spacing ratios. Peers share sizes; keep the scale small (13px is the established row/detail size). +- Apply alignment and icon rules 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. +Choose component role and size variant, then its container relationship. Compare height, radius, curve, inset and material together; equal radii alone do not establish coherence, and wrapping/expansion alone does not justify larger radii. [Radius standards](../../../docs/ui-radius.md#radius-scale) own values and exceptions. -- **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. +- **Inset:** coordinate inner/outer curves and inset. Radius subtraction is exact for concentric circular arcs; for superellipses, also inspect diagonal whitespace. +- **Flush or adjoining:** the enclosure owns exposed corners; internal joins stay square. Hover fills and pseudo-elements follow that contour without clipping menus or focus. +- **Independent child card/group:** use its own role/size tier, not the dialog radius or subtraction of all parent padding. +- **Circles/capsules:** preserve shape, including avatar container and image, using 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. +Keep fills, strokes and overlays geometrically stable across hover, pressed, selected, loading and disabled states. Reuse [card/elevation materials](../../../docs/ui-radius.md#settings-cards): shadows already include neutral hairlines; retain semantic state-colored borders without doubling neutral edges. -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. +Compare related controls, including small selection controls, at actual size in affected themes/states and relevant long-label/narrow layouts. Static checks reject unsupported declarations; rendered comparison judges fit. Consult [geometry cases](../../../docs/ui-design-review-cases.md#geometry) when needed. Apply to scoped changes, not bulk restyling. ## 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: +Follow [error handling](../dsh-error-handling/SKILL.md#localized-actionable-visible-reports). Choose feedback by message lifetime: -- **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. +- Transient success/failure uses the app-wide Toast, with state and rendering in a host that survives the reporting panel/tab, such as a `shell.overlay` entry. Do not toast pending states. +- Failed operations retain visible data; failed deletion keeps the row. +- Surface-owned failures use in-place notices: query failure with Retry or field validation. Keep a compact notice beside populated content; only empty panels center a full error state. +- Use short plain-language errors, preferably one sentence, without internal jargon except necessary diagnostic codes. Chinese notices of at most two sentences omit the trailing 句号（。）. Reserve space or overlay notices so neighbors do not shift. ### 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). +Lists use skeletons; other page-level loads center a bare spinner. Keep one loading treatment per page/component, including concurrent regions. Add loading text only when context requires it. ### Overlays and menus -Every menu, popover, and tooltip must be verified for all three before merge: +Before merge, verify every menu, popover and tooltip closes on outside click (and Escape when focusable), fits the viewport with an edge margin, and escapes ancestor clipping/neighbor coverage, using portals when needed. Flip only into a side that fits; never oscillate when neither fits. -- **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. +Use shared scrollbar styles and a small inset; bars must stay inside containers without being clipped by rounded corners or edges. ### 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. +New headers/pages account for macOS and Windows chrome. Menu, Modal and overlay primitives consume `--dsh-frame-top-clearance`; fix local macOS insets with scoped `[data-platform='darwin']` overrides and stylesheet assertions, not global-variable changes. Review the total clearance + page inset. ## 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. +Inspect the composition, then affected internal/cross-group relationships, distant peers and expanded content. Match both endpoints of axes; compare complete icon boxes before optical adjustments. Preserve popup/focus visibility, field feedback, narrow-layout actions and drafts. Check affected theme materials/platform backdrops. Full-interface claims cover all regions; fixtures/crops establish only what they render. ## Maintain one owner per rule -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. +Update the existing owner; add a skill and routing row only for a distinct decision. Keep examples in the [case reference](../../../docs/ui-design-review-cases.md); AGENTS and PR workflows link here instead of duplicating rules. -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. +Rule changes state applicability, decisions, exceptions and observable verification; update a distinguishing case and remove superseded statements elsewhere. Declare migration versus future-edit scope without implying existing UI conforms. Automate only mechanically decidable checks. Local review tools consume repository rules and retain source/rule revisions rather than maintaining another standards copy. ## Design review escalation -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. +Obtain designer/product review before landing new pages or interaction patterns, broad shared/global visual changes or unresolved tradeoffs. Routine local corrections need no extra checkpoint. Explicit independent reviews and periodic human audits may widen scope and feed recurring misses into rules; they supplement development checks and create no automatic schedule. diff --git a/.agents/skills/dsh-ui-alignment/SKILL.md b/.agents/skills/dsh-ui-alignment/SKILL.md index 46792262ab..e15db48ef0 100644 --- a/.agents/skills/dsh-ui-alignment/SKILL.md +++ b/.agents/skills/dsh-ui-alignment/SKILL.md @@ -1,44 +1,35 @@ --- 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. +description: Design or review DSH shared text columns, icon/label placement, tree indentation and centering. 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. +Apply within the [UI development loop](../dsh-client-ui-ux/SKILL.md#required-review-loop). Align comparable peers, including slots for optional icons and actions. ### Layout structure first, visual calibration second -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. +Distinguish click target, painted button, complete icon box and drawn contour. Intentional icon whitespace belongs to the layout box; enlarging a target must not move that box. Check containers, slots, columns, gaps and unintended overrides before optical corrections. Neither matching CSS boxes nor aligning every painted contour alone establishes balance. -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. +A glyph inconsistent across uses belongs to its icon owner. A composition-specific optical correction needs a scoped justification and comparison with peers. Preserve intended hierarchy: a child icon may align with parent text, but DOM nesting alone does not determine indentation. Extra hit padding is not a visible edge. -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. +Inline SVG `vertical-align: middle` follows font baseline/x-height, not visible text center. Check font, size, line height and icon box across CJK, Latin, monospace and wrapping. Do not make multiline links unwrappable just to center an icon. ### Choose both the object and the axis -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. +Name the aligned object and reference container. Equal padding need not align text starts; equal SVG dimensions need not align visible centers. -| 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 | +| Alignment | Required relationship | +|---|---| +| Left edge | Same-role labels and reading content share a deliberate text axis across relevant groups. | +| Horizontal center | Center the whole icon/label unit or empty-state stack in its named container. | +| Vertical center | Balance single-line peers visually while keeping stable clickable heights. | +| Baseline / first line | Align mixed-size text baselines; attach leading icons to the intended first line, not the whole paragraph. | +| Two edges | Anchor left/right groups to their respective edges; preserve internal gaps instead of distributing every icon. | +| Repeated columns | Align all corresponding slots, not just the last action. | -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. +For Chinese/English navigation, identify leading icon centers, text starts and trailing controls by role. Headings, avatars and expandable search may differ. Continue axes only where the composition establishes them, including shared plugin reading edges even when hover paint extends beyond them, and conversation/right-sidebar header heights and baselines. -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. +Center within the button, main pane or content remaining below headings/filters, as appropriate. A fixed top margin is not centering. When a short window cannot fit the group, preserve scroll access with a compact top-aligned layout instead of clipping. -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. +Normalize peer control sizes and slots before any necessary small optical offsets; verify comparable uses. Preserve usable hit targets and do not hide inconsistent parent layout with transforms. Check [spacing](../dsh-ui-spacing/SKILL.md) without moving the chosen axes; consult [cases](../../../docs/ui-design-review-cases.md#alignment) for uncertain judgments. diff --git a/.agents/skills/dsh-ui-icons/SKILL.md b/.agents/skills/dsh-ui-icons/SKILL.md index 16bb47173a..599c09fbe8 100644 --- a/.agents/skills/dsh-ui-icons/SKILL.md +++ b/.agents/skills/dsh-ui-icons/SKILL.md @@ -1,76 +1,59 @@ --- 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. +description: Select, draw, normalize or review DSH action, navigation, file and status icons. Covers system style, optical size, clarity and text relationships; 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. +Apply within the [UI development loop](../dsh-client-ui-ux/SKILL.md#required-review-loop), in the affected page or modal context. ## 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. +Search the library and comparable UI for the intended meaning and supported variants. Reuse the shared component; do not copy its SVG into a feature or create a near-duplicate. Size, color and placement mismatches belong to the variant or consumer layout, not a new drawing. -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. +Draw only when existing artwork cannot express the meaning or the user requests a distinct design. Identify the closest alternatives and unmet need. New glyphs require designer approval before landing; requested drafts can be prepared locally. Do not redraw a shared glyph to fix one consumer. -The [primitives catalog](../../../packages/client/ui-primitives/README.md#component-catalog) and icon source own the available variants and stroke values. [Official plugin artwork](../dsh-official-plugin-artwork/SKILL.md) owns package artwork, not action icons. +The [primitives catalog](../../../packages/client/ui-primitives/README.md#component-catalog) and icon source own available variants; [official artwork](../dsh-official-plugin-artwork/SKILL.md) owns package artwork. ## 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. +- Use minimal, geometric, functional glyphs with familiar meanings. Match peers in contour, endings, joins, weight, whitespace and complexity; avoid decorative, playful or illustration-like detail. +- Use simple geometry and restrained rounding. Around 1px at a 16px design size is a starting point for softened corners, not a rule for every turn. Preserve useful sharp corners. +- Default to monochrome outlines inheriting `currentColor`, without gradients, shadows, textures or 3D effects. Preserve intentional fills, status dots, selected marks and knockouts. File, site, plugin and brand artwork retain their own palettes and roles. +- Balance structure and whitespace without requiring symmetry. Preserve meaningful direction. Use gaps, overlap, nesting and broken obscured lines to clarify complex meanings; avoid accidental tangencies, dark knots and disappearing gaps at actual size. Do not force every subject into a closed outline. ## 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. +Establish meaning, placement, actual sizes, peers and states; ask only when missing information changes the design. Produce editable SVG with Regular and Medium variants sharing construction; intentional fill-only variants may share geometry. Tune silhouette, gaps, center and weight at intended size using component/theme conventions, not consumer-specific stroke or scale overrides. -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. +Deliver editable artwork and a rendered peer comparison, including its label or control when relevant. Explain the semantic choice and unresolved alternatives. Keep drafts local; when implementing, register reusable components and update their documentation. Distinguish review-ready proposals from approved glyphs. ## 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. +Preserve the original and recognizable form. Check existing equivalents, but do not substitute one when the user requested normalization of their drawing. Separate technical fixes (canvas, scale, stroke, color inheritance, placement) from silhouette or metaphor changes; identify any required simplification. -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. +Inspect SVG paths, transforms, fills, strokes and references. Reconstruct raster references without tracing rasterization or compression artifacts; identify interpreted details and ask about unrecoverable defining features. Deliver editable SVG and original/normalized/peer comparisons under identical conditions at intended size. Keep artwork changes separate from consumer layout fixes. ## Placement and use -Review the layout box, the painted glyph, and its relationship to neighbouring text as separate properties. +Distinguish click target, visible button base, icon slot and painted glyph. Equal targets or SVG dimensions do not imply equal optical size; compare silhouette, stroke, whitespace and center beside the label. Fix containers and unintended CSS overrides first. Correct shared artwork only when the imbalance follows it across uses. -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. +An icon and label for one action normally share foreground and state changes. Search icons and placeholders form one prompt; typed text and independent clear actions may differ. Verify opacity, stroke and background in both themes. Status, warning and brand roles may use different colors. Compare native file icons and folder outlines deliberately; do not normalize logos or status dots to toolbar icons. -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. +Use the shared Tooltip for unclear icon-only actions and HoverCard for informational content requiring hover or selection. [Responsive UI](../dsh-responsive-ui/SKILL.md) owns mobile tooltips and label collapse. Every right-sidebar tab needs a meaningful icon. Preserve accessible labels and focus; [alignment](../dsh-ui-alignment/SKILL.md) owns positioning and [spacing](../dsh-ui-spacing/SKILL.md) owns gaps. ## Optical size and clarity before implementation -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. +Ordinary menus use 14px Regular icons with 1px strokes; compact menus retain 12px. Permission triggers and settings-navigation peers use 16px slots; permission-menu rows retain 14px. Compare at the owning control's size, weight, colors and label, using an outlined circle and rectangular control as references. Open silhouettes may need more extent than dense fills; supporting chevrons, handles and dots keep their roles. Do not normalize by ink area or fill every view box. -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. +For softness, check CSS dimensions and ancestor transforms, view box and drawing bounds, stroke versus filled contour, device-pixel placement, then color/opacity. Non-16 view boxes are valid; compare identical artwork before attributing sharpness to inline SVG versus sprites. -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 stay **1 CSS px**, Medium **1.3 CSS px** across sizes. Use non-scaling strokes, including inline composites. Convert filled line contours to real strokes when consistent weight requires it; retain intentional silhouettes and knockouts. -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. +Check straight-stroke edges at actual DPR after all scaling: center and width jointly determine coverage. Round positioned overlays in device pixels only while preserving anchoring and viewport containment. Keep antialiasing on curves/diagonals; do not globally round paths or use `crispEdges` to hide placement errors. Partial coverage is legitimate for 1.3px strokes. ## 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. +Preserve a working-tree baseline. Compare final rasters under identical conditions in light/dark themes, at DPR 1/2, at 14px/16px and larger changed-consumer sizes. Judge recognition, peer consistency, clipping, center, gaps, fixed weight and text at actual size; enlarged views diagnose pixels only. + +After set-wide changes, inspect every glyph in both weights, including unchanged entries, composites and feature-local duplicates; consolidate semantic duplicates. Inventory all families, comparing file/site/plugin/brand artwork separately at their intended sizes. Full-set delivery shows every final glyph side by side, marks changed/unchanged entries and includes comparable before/after evidence. Consult [cases](../../../docs/ui-design-review-cases.md#icon-optics) for uncertain judgments. diff --git a/.agents/skills/dsh-ui-spacing/SKILL.md b/.agents/skills/dsh-ui-spacing/SKILL.md index 5063efd092..53813da1a1 100644 --- a/.agents/skills/dsh-ui-spacing/SKILL.md +++ b/.agents/skills/dsh-ui-spacing/SKILL.md @@ -1,26 +1,20 @@ --- 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. +description: Design or review DSH semantic grouping, internal/external spacing and repeated rhythm, including wrapped or expanded content. --- # 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. +Apply within the [UI development loop](../dsh-client-ui-ux/SKILL.md#required-review-loop). Distance should explain which text, input and action belong together. ### 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. +Group elements by one object, action or repeated unit, not DOM siblings, background or React component. State that relationship before positioning. Check each nesting level independently; larger outer gaps do not require larger inner gaps. -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. +Without an explicit divider, comparable neighboring groups need visibly greater separation between groups than within them. Equality is only a lower bound against reversal. Repeated compositions share gaps, padding and alignment; label length does not justify unrelated spacing. -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. +When wrapping, metadata, subgroups or independent actions increase complexity, increase enclosing separation enough to retain grouping. Do not derive gaps from card area or multiply every margin. Dividers and distinct surfaces may reinforce separation, but headings must remain closer to their own content than to preceding groups. -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 actual whitespace at normal size, including padding, line-height, glyph whitespace and borders. CSS margin ratios alone do not establish grouping; explanatory labels need one unambiguous owner. -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. - -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. +Reuse page spacing and [style tokens](../../../docs/web-styling.md), preserve [alignment](../dsh-ui-alignment/SKILL.md) axes, and consult [cases](../../../docs/ui-design-review-cases.md#grouping) for uncertain judgments. This skill defines no numeric scale.