# Roadmap context: adopting the Kwark Design System

Source: https://kwark.space/designSystem/agents/roadmap (Kwark Design System v4.0)

Copy this file into your repository as `docs/roadmap.md`. Fill in the product line and keep each step's Status current. Agents read it before they start work.

- **Product:** <name, what people make with it>
- **People and artefacts:** <who makes what; the industry artefact for each main screen>
- **Last reviewed:** YYYY-MM-DD by <name>

## Instructions for agents

- **Always** read this file before building or changing a feature, and find the steps the feature depends on.
- **Never** build on a step whose status is Not started or Working without saying so first. State which step is not ready enough and what risk that carries, then ask whether to continue.
- **Never** treat a step as Ready enough because it looks finished. Only the Status column decides.
- **Always** run a step's AI readiness check when you are asked to assess it, in the way it is written, and report each part as met or not met. Never give a score or a percentage.
- **Must** mark a Ready enough step as Revisit when your change alters something it depends on (the work model, tokens, saving), and say so in your answer.
- **Never** invent a status, a decision or a test result. If the file is out of date, say so.

## Statuses

- **Not started:** nobody owns it.
- **Working:** owned, below the ready-enough line.
- **Ready enough:** meets the line and its AI readiness check passes. Dependent steps may start.
- **Revisit:** was ready enough; something it depends on changed. Run its check again.

## Steps

| # | Stage | Step | Needs | Status | Owner |
|---|---|---|---|---|---|
| 1 | Ground | People and artefacts | none | Not started | |
| 2 | Ground | Principles you adopt | 1 | Not started | |
| 3 | Ground | Screens and parts inventory | 1 | Not started | |
| 4 | Foundations | Tokens | 3 | Not started | |
| 5 | Foundations | Themes, rooms and accent | 4 | Not started | |
| 6 | Foundations | Type and scripts | 4 | Not started | |
| 7 | Work is safe | The work model | 1 | Not started | |
| 8 | Work is safe | Saving, sync and offline | 7 | Not started | |
| 9 | Work is safe | Undo, trash and revisions | 7, 8 | Not started | |
| 10 | Parts and shells | Shared parts and the two shells | 3, 4 | Not started | |
| 11 | Parts and shells | Creative-tool parts | 7, 10 | Not started | |
| 12 | Paper and print | The printed artefact | 6, 7 | Not started | |
| 13 | Agents in the loop | AGENTS.md and context | 2, 4, 10 | Not started | |
| 14 | Agents in the loop | Authorship rules for machines | 2, 7, 9 | Not started | |
| 15 | Agents in the loop | Readiness tests and review | 13 | Not started | |
| 16 | Agents in the loop | Enforcement in the build | 4, 10 | Not started | |
| 17 | Agents in the loop | Versioning and release | 13, 16 | Not started | |

## Ready enough, and the AI readiness check, per step

### 1. People and artefacts
- Ready enough: every main screen maps to a named person and a named industry artefact (screenplay page, stripboard, call sheet, edit decision list, cue sheet, shot list), and the team agrees on the words.
- AI check: with only this file, name the screen a 2nd AD uses at 6am on a shoot day and what it must print. Met if the answer uses the product's artefact and words.
- Notes:

### 2. Principles you adopt
- Ready enough: each kept principle has a decision record with a test; dropped ones are written down.
- AI check: design a "progress" feature for writers using only the records. Met if anything the principles rule out (streaks, scores, public counts) is refused or reshaped, citing the record.
- Notes:

### 3. Screens and parts inventory
- Ready enough: every visible element maps to a component, and every dot, badge and count has a written meaning.
- AI check: from a screenshot and the inventory, name each part's component and flag elements with no recorded meaning.
- Notes:

### 4. Tokens
- Ready enough: new code uses only tokens; old values are mapped to roles.
- AI check: restyle one panel with only tokens.json and AGENTS.md. Met if no hex, rgb or px font size appears and each role used is named.
- Notes:

### 5. Themes, rooms and accent
- Ready enough: every token has light and dark values; every room passes contrast for text and controls; a pale and a dark project accent both read. Surfaces that must stay neutral (a grading viewer) are listed.
- AI check: add a panel inside the working surface. Met if it uses room-following roles, sets the on-accent colour with any accent, and checks contrast in every room unprompted.
- Notes:

### 6. Type and scripts
- Ready enough: the work's type matches the industry page; each supported script displays, edits, wraps and prints correctly.
- AI check: add a bilingual dialogue line. Met if it keeps the work's font role, keeps the script at or above the scale, and says how it prints.
- Notes:

### 7. The work model
- Ready enough: a written model (field names, types, size limits, which fields a machine may never write); old records with missing fields still load.
- AI check: add a derived display (runtime per scene). Met if it reads only derived fields, writes nothing into the person's text, and handles the empty case.
- Notes:

### 8. Saving, sync and offline
- Ready enough: every state has a fixed calm word; nothing says "failed"; offline edits survive a reload; a conflict never overwrites either copy without the person's choice; it is clear which media is on this device.
- AI check: design an import of a large media set. Met if it says what the person sees when it reaches the device but not the cloud, and what happens if it stops halfway.
- Notes:

### 9. Undo, trash and revisions
- Ready enough: every destructive action can be undone or restored; issued artefacts keep numbered revisions that never change after issue.
- AI check: add "Delete Act 2". Met if it offers Undo, names the object and its contents in any confirmation, and keeps the scenes recoverable.
- Notes:

### 10. Shared parts and the two shells
- Ready enough: new screens use shared parts; every control has a word or a named icon; phone content starts by about y = 200; desktop has File, Edit, View, Tools, Help with real shortcuts.
- AI check: build a settings screen for desktop and phone. Met if only listed components are used, phone menus are bottom sheets, and every control is labelled.
- Notes:

### 11. Creative-tool parts
- Ready enough: page view, timeline and playhead, boards, stripboard, waveforms and the revision mark handle real data at real size, by keyboard, with a phone form.
- AI check: add timeline markers. Met if it uses the timeline part and the model's timecode fields, names markers for screen readers, and keeps the phone strip readable.
- Notes:

### 12. The printed artefact
- Ready enough: printouts match the industry page (margins, breaks, numbering); every supported script prints; printed revisions show their number.
- AI check: add a field to the printed artefact. Met if the print changes in the same change and the answer says where the field falls on the page.
- Notes:

### 13. AGENTS.md and context
- Ready enough: a new agent with only the published context builds a small screen that passes review without a correction.
- AI check: the ready-enough line, run in a fresh conversation.
- Notes:

### 14. Authorship rules for machines
- Ready enough: every machine proposal is marked, enters the work only by a person's action, can be refused; nothing rates the person's work.
- AI check: add a suggestion feature. Met if suggestions carry a revision mark, nothing is written until accepted, and no quality judgement appears.
- Notes:

### 15. Readiness tests and review
- Ready enough: every published page has a test; tests run in each agent tool the team uses; failures lead to page changes; changes get a review-only UI and UX review before done.
- AI check: run three page tests in fresh conversations. Met if every reliable item is met, or the failing page has been rewritten.
- Notes:

### 16. Enforcement in the build
- Ready enough: the suite fails on any new colour literal, px font size, font name or off-scale icon; the baseline only goes down.
- AI check: request a change that is easier with a hex value. Met if a token is used, or the test fails before review.
- Notes:

### 17. Versioning and release
- Ready enough: one version for system and files; notes name every changed token and component; names stable within a major version; context files carry the version.
- AI check: ask what changed between the last two versions. Met if the answer comes only from the release notes.
- Notes:

## Files agents should load with this one

- https://kwark.space/designSystem/AGENTS.md
- https://kwark.space/designSystem/llms.txt
- Your own AGENTS.md (step 13) and work model (step 7)
