Kwark. Design System
Open Kwark

Story spine

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

ComponentsData visualisationIn the app

3 acts · 15 beats

<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>

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).

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

Do

Act 3 in red with Missing beats or a percentage “complete”.

Don’t

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

React

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

<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.

<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>
  • 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.

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

Give this Markdown to your coding agent or share its URL.

Open .mdllms.txt
Loading…