# Suggestion panel

> Proposals drawn from the writer’s own material, kept beside the page and not in it: a heading from an outline beat, a prop the script mentions.

Source: https://kwark.space/designSystem/components/suggestion-panel

## Usage

### What it is
A panel beside the page that holds what a machine found or moved from the writer’s own material, each with its source, its reason in one sentence, and its own answer. Two kinds, both on the [AI and authorship](https://kwark.space/designSystem/foundations/ai-and-authorship.md) *May* list:

| Kind | Example | Answer |
|---|---|---|
| Moved from the writer’s own words | The outline beat *Mira finds the splice in the edit suite, night* proposed as INT. EDIT SUITE – NIGHT | **Use heading** · **Edit** · **Not needed** |
| Found on the page | ZIPPO, *set in capitals, the way an element is introduced* | **Add to breakdown** · **Not needed** |

Its geometry is the editor’s real alternates panel (`.dialogue-alternates`, 300px), which holds the *writer’s own* other versions of a speech. The suggestion panel never offers versions of dialogue: a machine in Kwark does not write or rewrite the story (Decision 0002).

### When to use
- When the writer opens it, or asks for it, beside the scene it is about.

### When not to use
- To propose dialogue, action, character choices or "improved" lines. Never.
- To comment on quality: no *this scene is long*, no *weak heading* (Decisions 0002, 0004).
- For a large batch (all of Act 2): use [AI result review](https://kwark.space/designSystem/components/ai-review.md) so each item is decided on its own.

### The answers
| Variant | Use for |
|---|---|
| Use / Add | Puts it in the work. The mark leaves; the source stays in [history](https://kwark.space/designSystem/components/ai-undo-entry.md). |
| Edit | Puts it in, selected and still marked, so the first keystroke makes it the writer’s. |
| Not needed | Removes it, and the same proposal is not offered again. |

### Writing
- Group headings name the source: *From your outline*, *The script mentions*.
- The reason is a plain sentence a person can disagree with. No confidence percentages, no adjectives.

## Style

### Anatomy

1. **Panel**: 300px, 12px padding, 14px corners, 1px `--k-line`, `--k-surface`, `--k-shadow-pop` (it floats).
2. **Header**: scene and *suggestions*, 12px Poppins `--k-text-2`; Close 32px.
3. **Source group**: 12px Poppins 600, `--k-text-2`.
4. **Item**: 8px padding, 10px corners, 1px `--k-line`, 6px gaps: the proposal inside `.kw-rev-line` / `.kw-rev` (Courier Prime 13px for script text), the provenance label, the reason in 12px `--k-text-2`, then the answers.
5. **Answers**: small buttons; the one primary per item is Use or Add.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-surface` | #ffffff | #1a1a1a |
| `--k-line` | #e2e8f0 | rgba(255, 255, 255, .1) |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-rev` | #346a58 | #9fd4bf |
| `--k-rev-bg` | #e4f1eb | #1b2b25 |
| `--k-rev-line` | #8cc3ae | #4f8a74 |
| `--k-accent` | #98633f | #98633f |
| `--k-font-screenplay` | 'Courier Prime', 'Courier New', monospace |  |
| `--k-radius-sheet` | 14px |  |
| `--k-radius-card` | 10px |  |
| `--k-shadow-pop` | 0 1px 2px rgba(15, 23, 42, .06), 0 12px 32px rgba(15, 23, 42, .12) | 0 2px 6px rgba(0, 0, 0, .2), 0 16px 36px rgba(0, 0, 0, .55) |

## Code

### React

Use the HTML below with `kwark.css`. The example shows the markup and styling. Supply any application behavior described on this page.

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<div class="kw-alts" role="dialog" aria-label="Suggestions for Scene 12">
  <header><span>Scene 12 · suggestions</span><button class="kw-icon-button" type="button" aria-label="Close"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M18 6 6 18M6 6l12 12"/></svg></button></header>
  <p class="kw-alts__now">From your outline</p>
  <div class="kw-alts__item kw-alts__item--machine">
    <p class="kw-rev-line"><span class="kw-rev">INT. EDIT SUITE – NIGHT</span></p>
    <span class="kw-rev-label">* Suggested · from your outline, Act 2</span>
    <span class="kw-alts__why">From the beat “Mira finds the splice in the edit suite, night.”</span>
    <span class="kw-alts__acts"><button class="kw-button kw-button--sm kw-button--quiet" type="button">Not needed</button><button class="kw-button kw-button--sm" type="button">Edit</button><button class="kw-button kw-button--sm kw-button--primary" type="button">Use heading</button></span>
  </div>
  <p class="kw-alts__now">The script mentions</p>
  <div class="kw-alts__item kw-alts__item--machine">
    <p class="kw-alts__found"><span class="kw-badge kw-badge--info">Prop</span><b>ZIPPO</b></p>
    <span class="kw-alts__why">Set in capitals, the way an element is introduced.</span>
    <span class="kw-alts__acts"><button class="kw-button kw-button--sm kw-button--quiet" type="button">Not needed</button><button class="kw-button kw-button--sm kw-button--primary" type="button">Add to breakdown</button></span>
  </div>
</div>
```

## Accessibility

### Keyboard
| Key | Does |
|---|---|
| Tab | Moves through items and their answers. |
| Escape | Closes the panel; focus returns to the page where it was. |
| Cmd + Z | Undoes the last Use or Add. |

### ARIA
- `role="dialog"` named for its scene. Each item carries hidden text *Suggested from your outline* or *Found in the script*, so the mark is not visual only.
- Buttons are named with their object: *Use heading INT. EDIT SUITE – NIGHT*, *Add ZIPPO to the breakdown*.

## For agents

### Rules

- **Never** propose dialogue, action, story choices or rewritten lines; only find, move, carry or convert the writer’s own material (Decision 0002).
- **Must** keep proposals beside the page; nothing reaches the work without a person’s Use or Add.
- **Must** give each item its source, a one-sentence reason and its own Not needed; never Accept all into the script.
- **Always** remember Not needed so the same proposal is not offered again.
- **Never** open unasked or describe a proposal as better.

### AI readiness test

**Task:** Offer Scene 12's props and a heading from the outline beside the page.

**Give the agent:** This page, Revision mark, Provenance label, Foundations › AI and authorship.

**Constraint:** The writer asks for "a punchier line for Mira" in the same session.

**A reliable answer:**
- Offers ZIPPO under The script mentions with its reason
- Offers INT. EDIT SUITE – NIGHT from the beat with its source
- Declines to write or rewrite Mira's line and says Kwark does not write the story
- Per-item answers, no Accept all
