# Link

> Words that take you somewhere. A reference link points at a record in the film and carries its number, so "Scene 12" goes to the right Scene 12 even after the script is reordered.

Source: https://kwark.space/designSystem/components/text-link

## Usage

### What it is
A link goes somewhere and changes nothing. If pressing it saves, issues or deletes, it is a [button](https://kwark.space/designSystem/components/button.md). Kwark has three kinds:

| Kind | Class | Use |
|---|---|---|
| Inline | `kw-textlink` | Inside a sentence: *the Day 7 call sheet* |
| Quiet | `kw-textlink--quiet` | Standalone in a list or footer, underlined on hover |
| Reference | `kw-reflink` | A record in the film: a scene, a character, a page, a shot |

### The Kwark idea: references carry their number
Notes, comments and breakdown sheets talk about scenes constantly. A reference link stores the scene's id, and shows its current number in a small Courier box, as in the margin of the page, then its heading. Because it is stored by id, *Scene 12* still opens the right scene after the outline is reordered. On a locked script the number never changes; on a draft it updates itself. A scene that has been omitted keeps its link and says so: **14** *Omitted on pink, 15 Nov*. It never becomes a dead link or a 404.

### When to use
- Going to another record, page or module: *Mira’s page*, *the call sheet*.
- Leaving Kwark: with the ↗ glyph and *opens a new tab* in its name.

### When not to use
- For commands. For opening a menu. For anything that needs confirming.
- *Click here*, *Learn more* or *Read more*: the link text names the destination.

### Writing
- The words of the link are the destination: *Day 7 call sheet*, not *here*.
- Never add an arrow to an internal link; the underline says it is a link. The ↗ is only for leaving Kwark.
- A link someone cannot follow says why in its own words: *Breakdown (not shared with you)*.

## Style

### Anatomy

1. **Inline**: inherits the size around it; `--k-text`; 1px underline at 42% of the text colour, 0.22em below; full colour on hover.
2. **Quiet**: `--k-text-2`, no underline at rest; `--k-text` and underline on hover.
3. **Reference**: a number box (1px `--k-line`, 3px corners, Courier Prime 700 11px tabular) then the name; scene headings in Courier Prime, capitals by convention.
4. **Omitted**: number kept, name in `--k-text-2` saying when it was omitted.
5. **External**: a 0.9em ↗ drawn in SVG after the words and a hidden *opens a new tab*.
6. **Pressed**: `--k-text-2` for the moment of the press.
7. **Focus**: 2px `--k-focus` ring 2px out, 2px corners; the underline goes to full colour.
8. **Visited**: no change. Kwark is a workspace, not a reading list.

### Tokens

| Token | Light | Dark |
|---|---|---|
| `--k-text` | #0f172a | #e3e3e3 |
| `--k-text-2` | #5b6779 | #9ca3af |
| `--k-line` | #e2e8f0 | rgba(255, 255, 255, .1) |
| `--k-focus` | #0f172a | #f4f4f5 |
| `--k-font-screenplay` | 'Courier Prime', 'Courier New', monospace |  |
| `--k-fs-body` | 14px |  |
| `--k-fs-dense` | 11px |  |
| `--k-dur-1` | 120ms |  |

## 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
<p class="kw-prose-sample">Aanya’s note on <a class="kw-reflink" href="#scene-12" aria-label="Scene 12, INT. EDIT SUITE – NIGHT"><span class="kw-reflink__num">12</span><span class="kw-reflink__name kw-reflink__name--script">Int. Edit suite – night</span></a> asks for the splice two pages earlier. The new material is in <a class="kw-reflink" href="#scene-12a" aria-label="Scene 12A, EXT. ROOFTOP – CONTINUOUS"><span class="kw-reflink__num">12A</span><span class="kw-reflink__name kw-reflink__name--script">Ext. Rooftop – continuous</span></a>, and <a class="kw-reflink kw-reflink--omitted" href="#scene-14" aria-label="Scene 14, omitted"><span class="kw-reflink__num">14</span><span class="kw-reflink__name">Omitted on pink, 15 Nov</span></a> is gone from the shoot.</p>
<p class="kw-prose-sample">Mira is called at 06:30 on the <a class="kw-textlink" href="#call-sheet">Day 7 call sheet</a>. The location’s parking rules are on the <a class="kw-textlink" href="#council" rel="noopener" target="_blank">council’s filming page<span class="kw-visually-hidden">, opens a new tab</span><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="M7 17 17 7M8 7h9v9"/></svg></a>.</p>
<p class="kw-prose-sample" style="display:flex;flex-wrap:wrap;gap:16px">
  <a class="kw-textlink kw-textlink--quiet" href="#all-scenes">All scenes</a>
  <a class="kw-textlink kw-textlink--quiet" href="#mira">Mira’s page</a>
  <a class="kw-textlink" aria-disabled="true" role="link">Breakdown (not shared with you)</a>
</p>
```

## Accessibility

### Keyboard
| Key | Does |
|---|---|
| Tab | Moves to the link. |
| Enter | Follows it. (Space does not; that is a button's key.) |
| ⌘ Enter / Ctrl Enter | Opens it in a new tab, as the browser does. |

### ARIA and contrast
- A real `<a href>`. A link that cannot be followed uses `role="link"` with `aria-disabled="true"` and no `href`, and its text says why.
- Reference links have a name with the record type: *Scene 12, INT. EDIT SUITE – NIGHT*.
- The underline is the non-colour cue (WCAG 1.4.1): links in body text are always underlined.
- External links say *opens a new tab* in their accessible name.

## For agents

### Rules

- **Must** use a link only to go somewhere; anything that changes data is a button.
- **Must** store reference links by record id and show the record's current number, so reordering never breaks them.
- **Always** keep a link to an omitted scene working and saying "Omitted", never a dead link.
- **Never** add an arrow to an internal link; use the ↗ glyph only for leaving Kwark, with "opens a new tab" in its name.
- **Never** write "click here", "learn more" or "read more"; the link text names the destination.

### AI readiness test

**Task:** Let a breakdown note mention the scenes it affects.

**Give the agent:** This page, Breakdown page, revision.ts numbering.

**Constraint:** The outline is still being reordered; Scene 14 may be cut.

**A reliable answer:**
- Uses reference links stored by scene id
- Shows the current number in a Courier box and the heading
- An omitted scene's link says "Omitted on pink" and still opens
- No arrows on internal links
