dsh-super-code 0.3.11 → 0.4.0

package/presets/super-code/skills/super-code-frontend/references/interaction-states.md

@@ -1,51 +0,0 @@
-# Interaction and state continuity
-
-## Reduce physical and mental effort
-
-Start with the task people repeat and the input they actually use. A control should communicate its action, relate visibly to what it affects, and be easy to acquire without careful aiming. Preserve the application's familiar interaction conventions; each invented gesture or inconsistent behavior adds work for the user.
-
-- Place contextual actions near their content and keep frequent actions readily reachable. Reduce needless pointer travel, thumb stretching and repeated scrolling, without crowding controls. Thumb reach varies with device size, grip and handedness; do not assume one universal bottom corner. On a narrow screen, a wider primary control can be useful when it fits the reading and action flow.
-- Size the **hit area**, not merely the icon. Around 44 by 44 CSS pixels is a useful comfort starting point for frequent touch actions; it is not a universal Web minimum or a conversion of native platform units. Pointer-oriented dense tools may use smaller controls with sufficient separation. WCAG 2.2 AA target sizing generally requires at least 24 by 24 CSS pixels or a qualifying exception, including its defined spacing alternative. Check the relevant criterion and input context; minimum compliance alone does not establish comfort.
-- Use real control padding or a carefully bounded hit region to enlarge targets. Adjacent targets must remain distinct. If a row looks wholly actionable, its intended row area should respond; unrelated trailing actions need separate controls and hit regions, without nesting buttons or links.
-- Keep repeated actions in stable positions. Do not let a spinner, validation message or changing count move the control under the pointer. Reserve space where practical, and allow longer translated labels to wrap or reflow without becoming tiny.
-- Prefer simple actions for common tasks. Give drag, swipe, hover or precision gestures an appropriate button/keyboard alternative when they are needed for core functionality. Hover-only controls and narrow pointer paths into a submenu need another way to operate them.
-
-Group choices around the user's decision and reveal secondary options when needed. Use meaningful labels for unfamiliar actions rather than unexplained icons. Emphasis can distinguish a preferred action while secondary actions remain usable. Separate destructive actions from frequently repeated safe actions; do not make irreversible deletion the casual default.
-
-## Trace the user's action through the state
-
-List only the states relevant to the flow before editing: initial, pending, success, empty, invalid input and recoverable failure. Decide which are distinct. “No records yet,” “no search matches,” and “could not load” need different explanations and next actions.
-
-For async actions, specify the owner of the request, what can be repeated, when a response becomes stale, and what survives navigation or hiding. UI feedback must correspond to the actual operation: show pending work, prevent unintended duplicates, and show success only after the promised boundary succeeds.
-
-Keep the user's input on failure. Put a useful error near the affected field/action and provide a recovery path. A failed save should not close the editor or overwrite the draft with old server state. Use inline feedback for local validation; a toast alone is usually insufficient to repair a field.
-
-## Keep actions predictable and feedback proportional
-
-For direct manipulation, keep the action connected to its object: selection shows which item will change, dragging gives a visible preview, and cancel or undo follows the product's contract. If optimistic rendering is appropriate, reconcile failure and retain the recoverable data; never silently leave a failed change looking committed.
-
-Give immediate local acknowledgement of input, then distinguish pending work from completion. Put routine status beside the relevant action or content. Use an interrupting dialog for a decision that actually needs attention, not every ordinary success. Animation can explain a transition, but should not delay the next action or replace a persistent state cue.
-
-Keep feedback understandable without relying on color, motion or sound alone. Announce relevant status through accessible semantics without stealing focus for routine updates. A disabled control should have an understandable reason and next step when its unavailability is not obvious. Important errors and recovery actions should remain available long enough to use; an auto-dismiss toast is not their only home.
-
-## Choose one source of truth
-
-Represent mutually exclusive states directly. Two panels that must never both be expanded generally need one `activePanel` value, not two booleans plus corrective effects. Define what clicking the active header does from the requested behavior, rather than assuming an accordion convention.
-
-Separate stored data, editable draft, view/navigation state and transient request state where their lifetimes differ. Derive values instead of keeping redundant copies. Trace a changed state shape through initialization, URL/deep links, persistence, hidden/remounted views and reset behavior. Ensure asynchronous callbacks still address the current owner; replacing a shared state object can detach an editor from its rendered state.
-
-For autocomplete, filters or rapid navigation, cancel superseded requests or reject late results using request identity. Release listeners, timers, observers and subscriptions with their owner. A hidden panel and an unmounted panel have different lifetimes; neither automatically means the user intended to abandon a pending save.
-
-## Semantics and focus are functional behavior
-
-- Use native buttons, links, labels and input controls. Keep navigation as links and actions as buttons; set button types deliberately inside forms.
-- Keyboard operation must reach the primary flow, visible focus and recovery actions. Do not make hover the only way to discover or operate a control. For disclosures, expose expanded state and the controlled region.
-- A dialog needs an accessible name, intentional initial focus, contained keyboard navigation and focus restoration on close. A popover, menu and modal are different patterns; use an existing accessible implementation when available.
-- When hiding content, move focus if its current target disappears. Avoid intercepting an unrelated action inside a clickable header; verify the real nested hit areas.
-- For destructive actions, follow the product's confirmation or undo pattern. Prevent duplicate submissions; retain the context needed to recover from a failed operation.
-
-## Verify transitions, not just snapshots
-
-A useful check crosses a boundary: empty to loaded, edit to cancel, failure to retry, hidden to restored, pending to completion, old response to rejected stale result. Select transitions affected by the diff and exercise them through the real route/component.
-
-Use unit/component tests for deterministic state rules and browser checks for navigation, focus, geometry and real interaction. Force failures through an existing test seam or isolated fixture, not by corrupting the user's data. Separate simulated error handling from a live backend check. Add regressions for actual bugs; do not add tests that merely assert the implementation's strings.

package/presets/super-code/skills/super-code-frontend/references/visual-design.md

@@ -1,43 +0,0 @@
-# Visual direction and layout
-
-## Make the composition explain the product
-
-First identify what the visitor should notice, understand and do. A landing page may need one strong proposition and credible proof; an operational dashboard needs comparison, status and fast scanning. Choose hierarchy for that purpose before choosing decoration.
-
-For a new interface, state a compact direction: audience, tone, dominant layout, type hierarchy, palette and one distinctive visual idea. Express it in the implementation, not a long design essay. For an existing interface, derive these from adjacent screens, tokens and assets. A request to fix a panel is not a reason to redesign the whole product.
-
-Use specific, plausible copy and content. Match number formats, units, labels and empty values to the domain. Fake controls, repeated filler cards and decorative charts without interpretable axes make a page look finished while leaving it unusable. If data is a demonstration, label it and still support the intended interaction.
-
-## Hierarchy before effects
-
-- Give the primary action a clear place and distinguish secondary actions by emphasis. Several equally loud buttons weaken the decision.
-- Use size, weight, position and whitespace to form a reading order. Do not turn every content group into an elevated card: shared alignment, separators or a plain list often communicates structure more clearly.
-- Keep a small, consistent type and spacing system. Use the project's fonts; add fonts only when justified and authorized. Body text needs a comfortable measure and line height, while dense tools may need compact rows. Test actual long titles rather than tuning only a short placeholder.
-- Color should carry a purpose: action, status, grouping or atmosphere. Check text and controls against their actual backgrounds in each supported theme. For WCAG AA, ordinary text needs 4.5:1 contrast, large text 3:1; essential UI boundaries and indicators generally need 3:1. Do not use color alone to convey failure or selection.
-- Treat imagery, icons and motion as part of the content. Use supplied or available assets and the established icon system. Avoid broken image URLs, misleading placeholder pictures and arbitrary emoji as product icons. Purposeful transitions should show change; respect reduced motion and retain visible state feedback.
-
-When matching a reference, compare proportions, alignment, content density, typography and visual weight before chasing a pixel offset. Preserve the reference's intent while adapting to real content and viewport limits. Do not declare visual equivalence based on matching CSS values alone.
-
-## Align relationships, not isolated pixels
-
-Alignment tells people which items belong together. Establish the relevant shared anchors: a content leading edge, text baseline, column boundary or repeated action position. Indentation should convey actual hierarchy. Labels, values and controls that play the same role should follow the same alignment rule; unrelated elements need not all be centered.
-
-- Put repeated rows on a common grid or layout primitive. Use shared gaps and padding instead of independent margins, spaces in text, or per-item translations. If the same role needs repeated offset patches, inspect its parent layout and component variants.
-- Align mixed-size text by baseline where it forms a reading row. An icon's box center may differ from its visible center; correct a demonstrated optical imbalance locally, while preserving its hit area and the surrounding layout rules.
-- Distinguish three boundaries: the box participating in layout, everything visibly painted, and the region that receives input. Focus outlines, shadows, selection rings, animation and expanded controls can exceed the layout box. Leave room for their meaningful states without clipping feedback or moving labels with every state change.
-- Let content and text sizing determine row height where wrapping is legitimate. A fixed height plus longer copy, a different font or larger text often creates the apparent alignment bug. Fix the sizing constraint before shrinking type or hiding information.
-- In diagrams, connectors, labels and nodes need coordinated geometry. Changing the node size without updating link anchors or label clearance creates collisions; test selected and running states as well as the resting geometry.
-
-For a reported offset, compare the relevant edges/baselines and computed parent layout in the actual state. Determine whether the cause is padding, line height, flex shrink, grid sizing, overflow, a transform, font loading or an overlay. Use a shared rule to fix a shared relationship; use a small optical correction only when the visible shape warrants it. Intentional asymmetry is valid when it clarifies hierarchy.
-
-## Responsive behavior is content behavior
-
-Choose breakpoints where the content stops fitting. Let primary content lead when columns collapse, keep important actions reachable, and use intrinsic layout before accumulating fixed widths. A desktop screen squeezed smaller is not a mobile layout.
-
-Inspect the actual containing surface: a sidebar, embedded pane or dialog may be narrow inside a large viewport. Flex/grid children often need `min-width: 0` or `minmax(0, 1fr)` to let text wrap. Fix the element causing overflow instead of masking the whole page with `overflow-x: hidden`.
-
-Use explicit overflow behavior for dense tables or code; retain headers/context and an obvious scrolling region. Sticky bars must not cover focus targets or the final content row. Account for safe-area insets on edge-to-edge surfaces and the on-screen keyboard when they affect the supported device. Check zoom, longer localized strings, touch targets and theme changes when relevant to the requested surface.
-
-## Refine from an observation
-
-Describe a concrete defect: “the action is below the fold at this width,” “this label overlaps the selection ring,” or “the empty state reads like an error.” Trace it to layout, state or styling. Change that cause, then inspect the same content/state/viewport again. Wait for fonts, assets and transitions to settle before evaluating a screenshot; a transition frame is not the final palette.