# Story spine

> The whole story at a glance above the Structure view: a band per section, a dot per beat. It measures, never judges.

Source: https://kwark.space/designSystem/components/story-spine

## Usage

### When to use
At the top of the Structure view, so a writer returning after a week sees the shape of what they have before they scroll (Decision 0031). Re-entry is the costliest moment for a writer with a day job.

### When not to
- Never as a tension curve or a "story health" chart. Rejected in 0031 under 0004: tension sliders are teaching.
- Never colour a section as "too short" or "empty" (0002, principle 6). An empty section says *No beats yet* in grey.

### Every mark means one thing
| Mark | Means |
|---|---|
| Band | A section. Its length is the share the writer gave it ("Act 1 (25%)") or an even split. |
| Segment | A part inside the section. |
| Dot | One beat. Up to 12, then "+n". |
| Total line | Sections and beats, counted. |

### Writing
Visible name: "The story at a glance". "Spine" lives only in code and records, because a structure template is called *The Pixar Story Spine* (0031 history).

**Do:** Act 3 drawn at its planned 25% with *No beats yet* in grey.

**Don't:** Act 3 in red with *Missing beats* or a percentage "complete".

## Style

### Anatomy

One `<li>` per section with `flex-grow` = its share. Band 28px, 6px corners, 2px top rule in `--kw-act`, parts at 22% of the act colour (34% on hover), 5px dots. Name 12px 500, meta 12px `--k-text-2`. On phones the strip keeps one row and the acts share the width; each is at least 44px tall.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-cal-writing` | #98633f | #e8b58b |
| `--k-cal-rehearsal` | #4f7359 | #86b392 |
| `--k-cal-recce` | #4d6a7a | #83aac0 |
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-radius-control` | 6px |  |

## Code

### React

In the Kwark app: `import StorySpine from '@/pages/Understanding/StructureBoardModule/components/StorySpine'`.

```tsx
<StorySpine acts={acts} blocks={blocks} onChoose={actId => scrollToAct(actId)} />
```

| Prop | Type | Notes |
|---|---|---|
| `acts` | `StructureBlock[]` | sections, in order |
| `blocks` | `StructureBlock[]` | parts and beats |
| `onChoose` | `(actId: string) => void` | scrolls the Structure view to that section |

### HTML and CSS

Works anywhere with `kwark.css`.

```html
<nav class="kw-spine" aria-label="The story at a glance">
  <ul class="kw-spine__strip">
    <li style="flex-grow:25"><button class="kw-spine__act" type="button" style="--kw-act:var(--k-cal-writing)" aria-label="Act 1, 25 percent, 6 beats"><span class="kw-spine__band"><span class="kw-spine__part"><i></i><i></i><i></i><i></i><i></i><i></i></span></span><span class="kw-spine__name">Act 1</span><span class="kw-spine__meta">6 beats</span></button></li>
    <li style="flex-grow:50"><button class="kw-spine__act" type="button" style="--kw-act:var(--k-cal-rehearsal)" aria-label="Act 2, 50 percent, 2 parts, 9 beats"><span class="kw-spine__band"><span class="kw-spine__part"><i></i><i></i><i></i><i></i></span><span class="kw-spine__part"><i></i><i></i><i></i><i></i><i></i></span></span><span class="kw-spine__name">Act 2</span><span class="kw-spine__meta">2 parts · 9 beats</span></button></li>
    <li style="flex-grow:25"><button class="kw-spine__act" type="button" style="--kw-act:var(--k-cal-recce)" aria-label="Act 3, 25 percent, no beats yet"><span class="kw-spine__band"><span class="kw-spine__part"></span></span><span class="kw-spine__name">Act 3</span><span class="kw-spine__meta">No beats yet</span></button></li>
  </ul>
  <p class="kw-spine__total">3 acts · 15 beats</p>
</nav>
```

## Accessibility

- It is navigation: `<nav aria-label="The story at a glance">` with one button per section.
- Each button is named with the section, its share and its counts, because dots and lengths are visual.
- Focus ring 2px, 3px offset, around the whole act.

## For agents

### Rules

- **Never** colour or label a section by judgement (short, empty, weak).
- **Must** size bands by the writer's own share or evenly, never by an ideal.
- **Must** name each section button with its share and counts.
- **Never** show the word "spine" to writers.

### AI readiness test

**Task:** Add the story at a glance to a new structure template picker preview.

**Give the agent:** Story spine, Decision 0031, Decision 0004.

**Constraint:** Templates may have ranged shares such as "(0–10%)".

**A reliable answer:**
- Ranged share counts as its width
- Name drops the share text
- No ideal lengths or warnings
- Buttons named with share and counts
