# dsh-next-prompt Design System

## 0. Research Log

- Existing DSH Web `0.1.1-rc.2` and the previously verified `tools-dsh` next-prompt dock were used
  as the concrete visual contract; no redesign or external brand treatment was introduced.
- Public client contracts confirmed `conversation.input.dock`, session/input snapshots, and
  `inputActions.setDraft` as the supported integration surface.
- Imagen and Lazyweb lanes were skipped because this is a parity extraction of an existing shipped
  primitive rather than a greenfield visual direction.

## 1. Atmosphere & Identity

The suggestion is a quiet, native-feeling continuation of the DSH composer. It is subordinate to
the draft field and becomes memorable through its precise timing and safe fill-only interaction,
not decorative branding.

## 2. Color

All color roles use DSH-provided `--dsw-*` CSS custom properties. No package-owned raw color is
allowed. The resting surface uses the existing hover layer, tertiary text, and level-two border;
hover and focus elevate only through official interactive and business-state tokens.

## 3. Typography

The button inherits the DSH composer font. The single-line suggestion uses the host product's body
scale, weight, and line-height; this package introduces no font family or independent type scale.

## 4. Spacing & Layout

- Base unit: 4px.
- Dock width: official `--dsh-composer-card-max-width`.
- Side clearance: official `--dsh-composer-side-clearance`.
- Outer gap: 8px below the row.
- Button minimum height: 36px.
- Button padding: 4px block, 12px inline.
- Radius: 8px.
- Layout primitive: one full-width dock row with one intrinsic semantic button.
- Responsive behavior: the same composer-owned width contract at 375px, 768px, and 1280px with no
  horizontal scrolling.

## 5. Components

### NextSuggestionDock

- **Structure**: wrapper `div`, semantic `button`, single truncating `span`.
- **Variants**: hidden, generating, ready, stale. Only ready renders a DOM surface.
- **States**: default, hover, focus-visible, native active, reduced-motion.
- **Accessibility**: accessible name `Fill draft with suggested prompt`; native click, Enter, and
  Space activation; visible focus outline.
- **Motion**: opacity-only entrance using DSH fast duration/easing tokens; disabled for reduced
  motion.
- **Layout**: composer dock row; the host composer owns width and scroll behavior.

## 6. Motion & Interaction

Only opacity animates when a ready suggestion enters. Hover communicates interactivity through host
surface and label tokens. Selecting a suggestion calls only `setDraft`; it never submits or changes
conversation history.

## 7. Depth & Surface

Strategy: borders plus host tonal shift. The button has one DSH level-two border and one official
interactive background. No shadows, blur, gradients, or package-owned elevation layers are added.

## 8. Accessibility Constraints & Accepted Debt

- Target: WCAG 2.2 AA under the host DSH theme.
- Full keyboard reachability and visible focus are mandatory.
- Reduced motion disables the entrance transition.
- The suggestion stays one physical line and truncates visually without changing its accessible
  name or draft value.

Accepted debt: the public DSH `0.1.1-rc.2` composer exposes no supported ghost-text, placeholder,
Tab, or ArrowRight acceptance seam. Dock fill UI is therefore intentional. DOM mutation, synthetic
keyboard interception, composer replacement, and automatic submission are explicitly prohibited.