Interactive TUI & Token Authoring Wizard

[GarthDB]

Interactive TUI & Token Authoring Wizard

Status: Implemented — Shipped ✓ M0–M5 complete. Epic #980 closed 2026-05-26.

Relation to RFC family: UX layer on top of RFC-C — Agent-Readable Surface (Phase 8, epic #830). Not a conformance requirement of the agent surface; consumes the same Tool catalog and primer.

Spec version target: 1.0.0-draft

Coordination: docs/rfc-coordination.md — row added; all open questions resolved. Authoritative crate: sdk/tui/ (design-data-tui). Consumes spec/agent-surface.md.

---

1. Summary

Add a fourth transport to the design-data toolchain — an interactive TUI (design-data tui) built on Ratatui + crossterm, living as a new crate at sdk/tui/ alongside the existing sdk/cli/. The TUI consumes the same resolver, validator, and query crates that already power the subcommand CLI and the MCP server; no spec changes, no IPC, no JSON round-trip.

The flagship command is a four-screen token-authoring wizard that exercises the eventual write_token operation and makes the cascade, mode-set behavior, and rationale capture legible to designers through use. The wizard is the demo flagship; the surrounding TUI is the surface that makes everyday agent-surface operations (resolve, query, validate, describe, suggest, diff) feel like a session rather than a series of one-shot invocations.

---

2. Problem statement

The agent-readable surface (RFC-C / Phase 8) defines a CLI, an MCP server, and a Claude Code Agent Skill — all backed by the same resolver, validator, and query implementations. The existing design-data CLI is normative for headless and agent use: JSON when stdout is not a TTY, human-friendly when it is.

That leaves a gap. The "human-friendly when TTY" mode of a subcommand CLI is fundamentally non-stateful — every invocation re-parses the manifest, re-loads the cascade, and emits one shot of output. For three audiences this is the wrong shape:

• Designers authoring tokens. They need feedback loops measured in keystrokes, not invocations. A wizard that walks them through the cascade, naming, and mode-set decisions is the obvious teaching surface.
• Design system engineers debugging cascades. They want a long-running session with the dataset loaded once, then to flip between resolve_token, query_tokens, and validate_usage calls without restart cost.
• Demo audiences. Subcommand CLIs do not demo well to non-CLI viewers. A TUI with visible state, a command palette, and live diagnostics is legible from across a room.

Non-goals

• Replacing the subcommand CLI. The TUI is additive; design-data validate ./tokens must keep working.
• Defining new spec operations. The TUI consumes the existing Tool catalog and primer.
• Embedding agent loops. The TUI is for humans; the MCP server is for agents. They share a core but not a process.
• Cross-platform polish beyond what Ratatui + crossterm give for free. macOS + modern Linux terminals are the target; Windows works but is not a release blocker.

---

3. Proposed solution

Two parts: the TUI shell (§3.1–§3.7) and the token-authoring wizard that runs inside it (§3.8–§3.17).

3.1 Stack choice

Ratatui + crossterm, in the existing Cargo workspace, as a new crate at sdk/tui/ (sibling to sdk/cli/).

Rationale:

• The SDK core is already Rust (sdk/core/src/report.rs, cascade::resolve, query::filter, validate::validate_*). A Rust TUI calls those crates directly — no IPC, no JSON round-trip, no shelling out to design-data. This collapses the feedback loop the TUI exists to provide.
• Ratatui is the active successor to tui-rs, with a healthy widget ecosystem and immediate-mode rendering that handles resize and partial redraws cleanly. Demo-quality (no flicker, fast input) falls out of the framework rather than requiring per-screen care.
• Alternative stacks considered and rejected: Ink (TS) would force shelling out or duplicating the resolver in Node — adds a process boundary and slows iteration; Bubble Tea (Go) has the best ergonomics in the space but introduces a second toolchain for the workspace.

3.2 Companion crates

Crate	Purpose
ratatui	Core rendering and widgets
crossterm	Terminal backend, input, mouse
tui-input	Single-line text input (palette prompt, wizard fields)
tui-textarea	Multi-line input (rationale capture, query expressions)
nucleo	Fuzzy matcher for palette and token search (the matcher Helix uses; handles large corpora cleanly)
similar	Diff computation for the wizard's confirm screen
arboard	Clipboard for "copy resolved value" affordance
syntect	Optional syntax highlighting for JSON/YAML preview panes

3.3 Layout model

Three persistent regions, plus a transient modal layer for the wizard and other multi-step flows.

┌─────────────────────────────────────────────────────────────┐
│ Primer header — specVersion · manifest · mode sets · count  │  1 line
├─────────────────────────────────────────────────────────────┤
│                                                              │
│   Active view                                                │  flex
│   (results, describe panel, diff, etc.)                      │
│                                                              │
├─────────────────────────────────────────────────────────────┤
│ : palette prompt                                             │  1 line
└─────────────────────────────────────────────────────────────┘

Primer header is populated once at session start by calling the primer operation against the dataset path. It re-renders only when the manifest changes (e.g. the user switches datasets via :open).

Active view is owned by whichever command produced the current output. Each tool-catalog operation maps to a view type:

Operation	View
resolve_token	Single-token detail panel (literal value, file, UUID, specificity, cascade chain)
query_tokens	Filterable table — name, value, file, mode-set context
validate_usage	Diagnostics table grouped by rule_id / severity, with instance_path jump-to
describe_component	Component anatomy + states + tokenBindings (per Phase 6.7 return shape)
suggest_token	Ranked candidates with rationale, alias action inline
get_guidance	Markdown render (glamour-equivalent) of attached document blocks
diff_datasets	Side-by-side DiffReport with semantic-diff coloring

Palette prompt is the universal entry point. Empty buffer + first keystroke opens a fuzzy command list; typing / switches to query-expression mode; typing : is explicit command mode. Up/down arrows recall history (in-memory ring buffer, 100 entries, persisted to ~/.local/state/design-data/history between sessions).

3.4 State model

struct App {
    dataset: DatasetHandle,        // resolver/query/validate handles, loaded once
    primer: PrimerPayload,         // cached primer result
    history: VecDeque<Command>,    // command history ring buffer
    palette: PaletteState,         // input buffer, matcher, current candidates
    view: ActiveView,              // enum over the view types above
    modal: Option<Modal>,          // wizard, confirm dialogs, etc.
    clipboard: arboard::Clipboard,
}

enum ActiveView {
    Empty,
    Resolve(ResolveView),
    Query(QueryView),
    Validate(ValidateView),
    Describe(DescribeView),
    Suggest(SuggestView),
    Guidance(GuidanceView),
    Diff(DiffView),
}

enum Modal {
    Wizard(WizardState),           // see §3.8
    ConfirmWrite(WriteDiff),
    ManifestSwitch(ManifestPicker),
}

DatasetHandle wraps the same resolver/query/validate handles that sdk/cli/ uses. Loaded once at startup or on :open <path>; subsequent commands are cheap.

3.5 Key bindings (initial proposal)

Key	Action
:	Open palette in command mode
/	Open palette in query-expression mode
Esc	Close modal / clear palette / return to previous view
Tab / Shift-Tab	Move between focusable regions in modals
↑ / ↓	Navigate list / recall history (palette only)
Enter	Execute command / confirm selection
y	Yank (copy) selected value to clipboard
g then t	Goto token by UUID (palette shortcut)
g then c	Goto component by name
?	Help overlay
Ctrl-C / q (when palette empty)	Quit

The g-prefixed bindings are deliberately Helix/Kakoune-flavored — designers who already use modal editors get an accelerator; everyone else uses the palette.

3.6 Manifest awareness

The spec is normative on this: when a manifest is present, query_tokens and resolve_token MUST respect include/exclude and apply manifest overrides before returning results. The TUI surfaces this in two ways:

• The primer header shows the active manifest name. Clicking it (or :manifest) opens a ManifestSwitch modal that lists discoverable manifests in the dataset.
• A subtle indicator in the active view shows when results are manifest-filtered (e.g. "Showing 247 of 1,832 tokens · filtered by spectrum-web manifest").

Swapping manifests without restart is a deliberate demo affordance — it shows the same authoring session producing different results for different consumers, which is the core value prop of manifest-based filtering.

3.7 Output mode parity

The spec's TTY/non-TTY rule applies to the subcommand CLI. The TUI inverts it: we are always in a TTY, so every view is fully expressive (syntax-highlighted JSON, collapsible trees, color-coded diagnostics, mouse-scrollable tables).

For demos and bug reports, every view supports y a (yank all) which copies the underlying JSON payload to the clipboard — the exact bytes the non-TTY CLI would have emitted. This keeps the TUI and CLI semantically equivalent for any given command, while letting the TUI render that payload however it wants.

3.8 Wizard framing

The wizard is the first non-trivial command in the TUI and the demo flagship. It is a guided front-end for the eventual write_token operation, which is RECOMMENDED-not-NORMATIVE in v1 and marked Phase 8.x / not yet implemented.

Design goal: a designer authoring their first product-layer token should finish the wizard understanding why their token landed where it did. The wizard succeeds if a designer who completes it once can do the same thing in :new token without the wizard the second time.

3.9 The seven implicit decisions

A token authored "the right way" satisfies, in roughly this order:

1. Layer — foundation, shared structure, component, or product extension
2. Intent — what the token is for (drives property and name-object selection)
3. Name-object fields — the active taxonomy fields per the primer
4. Mode-set coverage — values across active mode sets (colorScheme, scale, etc.)
5. Value or alias — literal value or alias to an existing token (alias preferred)
6. Validation — validate_usage clean on the proposed fragment
7. Rationale — captured per the Product context — Agent capture behavior RECOMMENDED behavior

Doing these as seven sequential screens is the obvious move and the wrong one — too long, designers abandon. The wizard collapses these into four screens with progressive disclosure and smart defaults.

3.10 Screen 1 — Intent

Purpose: Make creating a duplicate token harder than reusing one.

Single text field: "What is this token for?" Free-form natural language.

As the user types (debounced ~250ms), the wizard calls suggest_token with the current text plus any property hint inferred from the words. Results render below the input as a ranked list with their cascade context.

If the top result has a confidence above a threshold (TBD — depends on suggest_token's scoring; initially we can use a simple cosine-similarity threshold over name-object fields), the wizard surfaces a banner:

These tokens already exist for similar intents. Reusing one keeps the cascade healthy.
Press a to alias to a result, or Enter to continue creating a new token.

The "alias to existing" path short-circuits the rest of the wizard — it goes straight to Screen 4 (rationale + confirm) with the alias pre-filled. This is the reuse-first path.

The "create new" path continues to Screen 2.

Spec dependencies: suggest_token (RECOMMENDED in v1). If not yet implemented, the wizard falls back to a fuzzy match over query_tokens results — degraded but functional.

3.11 Screen 2 — Classification

Purpose: Make the naming system visible by making name assembly live.

Three regions on one screen:

┌─ Layer ──────────────────────────────────────┐  ┌─ Live preview ──────────────┐
│ ( ) foundation                                │  │                              │
│ ( ) shared-structure                          │  │ color-background-card-hover  │
│ ( ) component                                 │  │                              │
│ (•) product-extension                         │  │ → product/tokens/card.json   │
└───────────────────────────────────────────────┘  │                              │
                                                    │ Cascade:                     │
┌─ Property ───────────────────────────────────┐   │   foundation:                │
│ background-color           ▼                  │   │     color-background-hover   │
└───────────────────────────────────────────────┘   │   → product (this):          │
                                                    │     color-background-        │
┌─ Name-object fields ─────────────────────────┐   │     card-hover               │
│ component:  card                              │   │                              │
│ state:      hover                             │   └──────────────────────────────┘
│ variant:    (none)                            │
│ emphasis:   (none)                            │
└───────────────────────────────────────────────┘

The live preview panel updates on every field change. It shows the assembled token name, the file it would be written to, and the cascade position relative to existing foundation/structure layers.

Live validation runs each time a field changes — diagnostics from validate_usage (Layer 1 and Layer 2 per sdk/core/src/report.rs) render inline below the relevant field, not in a global footer. This is the part that turns the wizard into a teaching tool: a SPEC-NNN diagnostic with its message next to the field that caused it.

Name-object fields are populated from the primer's taxonomyFields. Vocabulary autocomplete pulls from each field's declared values.

3.12 Screen 3 — Values across modes

Purpose: Make mode-set thinking visible by making the matrix concrete.

A table whose rows are mode-set combinations derived from the primer's modeSets. For a typical Spectrum dataset:

┌──────────────┬─────────┬───────────────┬──────────────────────────────────┐
│ colorScheme  │ scale   │ source        │ value                            │
├──────────────┼─────────┼───────────────┼──────────────────────────────────┤
│ light        │ desktop │ ◉ alias       │ background-color-hover           │
│ light        │ mobile  │ ◉ alias       │ background-color-hover           │
│ dark         │ desktop │ ◉ alias       │ background-color-hover           │
│ dark         │ mobile  │ ○ literal     │ #2a2a2a                          │
└──────────────┴─────────┴───────────────┴──────────────────────────────────┘

Every cell defaults to alias, pre-populated with suggest_token results scoped to that mode-set combination. The designer's job is to confirm or override, not author from scratch.

Switching a row from alias to literal requires the designer to fill in a value — and the cell turns subtly different (background tint or marker) to signal the divergence. This visual nudge is intentional: literal values in a product extension should feel exceptional, not routine.

Spec dependencies: resolve_token (NORMATIVE) for previewing what each alias resolves to in that mode-set context. The wizard calls resolve_token per row to populate a small "resolves to" hint next to the alias name.

3.13 Screen 4 — Rationale & confirm

Purpose: Capture the why, validate the whole, preview the write.

Three stacked regions:

Rationale (multi-line text, required, no character limit but soft-warned over ~280 chars):

Why does this token exist? What product or design decision drove the need for a new entry rather than reuse?

This text gets recorded in two places per Product context — Agent capture behavior: the token's inline rationale field and the product-context document's overrides[].rationale or extensions.tokens[].rationale.

Diagnostics — a final validate_usage run on the assembled fragment. Any errors block the confirm button; warnings show but don't block.

Diff preview — what's about to change on disk. Two diffs side by side: the new/modified token file, and the product-context.json update. Rendered with similar-driven coloring.

Confirm writes. Cancel discards. Both leave a history entry so the wizard can be resumed with :wizard last.

3.14 Wizard state model

struct WizardState {
    screen: WizardScreen,
    intent: String,
    suggested: Vec<SuggestionResult>,
    chosen_path: WizardPath,         // CreateNew | AliasToExisting(TokenUuid)
    classification: Classification,
    values: HashMap<ModeCombo, ValueSpec>,
    rationale: String,
    validation: ValidationReport,
    // Shared across screens; each screen mutates its own slice.
}

enum WizardScreen { Intent, Classification, Values, Confirm }
enum WizardPath { CreateNew, AliasToExisting(TokenUuid) }

struct Classification {
    layer: Layer,
    property: PropertyId,
    name_object: BTreeMap<TaxonomyField, FieldValue>,
}

enum ValueSpec { Alias(TokenUuid), Literal(Value) }

The state survives across screens; Tab/Shift-Tab jumps between screens once they've been touched (so power users can fly past Screen 1 if intent is already clear).

3.15 What the wizard exercises in the write path

When the user confirms, the wizard calls write_token (Phase 8.x, eventually) with:

• The assembled token object
• The rationale string

The implementation gates this behind --allow-write until write_token lands in sdk/core/. Pre-write_token, the confirm step emits a JSON payload to a temp file and offers :diff against the dataset — enough to demo the full wizard flow without a real write path.

3.16 Failure modes worth designing explicitly

• No suggest_token implementation yet → fall back to query_tokens fuzzy match; banner says "showing existing tokens (suggestion ranking unavailable)."
• Validation fails on confirm → block, focus the first failing field on the relevant screen, render the diagnostic message + suggested fix inline.
• Designer aborts mid-wizard → state persists in-process; :wizard resume reopens at the last screen. State is not persisted to disk across sessions in v1.
• Manifest changes mid-wizard → cascade and name-object vocabularies may shift. Wizard re-validates on resume and surfaces any new diagnostics.

3.17 Demo storyline

The storyline the wizard is built backward from:

A designer wants to add a hover state to a custom card component in their product extension. They open the TUI, hit :new token, type "card hover background" in Screen 1 — and the wizard immediately surfaces background-color-card-hover from somewhere in the cascade. Surprise: it exists. They press a to alias, write a one-line rationale, confirm. Done in 20 seconds.

Then a second pass: same designer, similar intent, but now they need a darker hover specifically for their product's marketing surface. The wizard walks them through Screens 2 and 3, shows the cascade implications on the preview pane, captures their rationale ("marketing surfaces need stronger affordance per brand guidelines"), validates clean, writes.

Both paths shipped in the same demo show the system's range — reuse first, override when justified — and the rationale capture pays off visibly in the product-context.json diff.

This is what M3 has to deliver.

---

4. Phased plan

All five milestones (M0–M5) shipped — table preserved as historical record.

M	Scope	Exit criteria
M0	Scaffold sdk/tui/, primer header, palette opens & closes	cargo run -p design-data-tui ./fixtures/spectrum shows the primer header and an empty active view
M1	query_tokens end-to-end	Typing :query background-color/* returns a filtered table; up/down navigates; y yanks selected row
M2	resolve_token, describe_component, validate_usage views	Each command produces a usable view; : palette autocompletes operation names
M3	Wizard modal	All four wizard screens work against a fixture dataset, end with a diff-preview confirm
M4	write_token integration	Wizard confirm writes a token file and updates product-context.json; gated behind --allow-write until write_token lands in sdk/core/
M5	Polish — mouse support, help overlay, persisted history, theming	Demo-recordable end-to-end without manual cleanup between takes

---

5. Out of scope (for v1)

• Replacing the subcommand CLI. The TUI is additive.
• New spec operations. The TUI consumes existing tool-catalog operations only; any new operation it would benefit from (e.g. write_token) is owned by RFC-C / Phase 8 follow-ups.
• Agent loops inside the TUI. Humans only; agents go through MCP.
• Cross-platform polish. Windows works at best-effort; macOS + modern Linux terminals are the release target.
• Wizard for foundation/structure layers. The wizard targets product-extension authoring. Foundation-token authoring is a different audience and probably needs a different surface (or no wizard at all).
• Persisting wizard drafts across process restarts. In-memory only in v1.

---

6. Open questions

All open questions are resolved — see the status block above and the inline comments on this discussion for per-question history (Q1: PR #996; Q4: PR #995; Q5: terminal-native; Q6: single sdk/tui/).

---

7. References

RFC family touch points

• #714 — Spectrum Design Data Specification (umbrella) — parent
• #832 — RFC-A: Component Contract — describe_component view consumes this contract
• RFC-C — Agent-Readable Surface (epic #830, spec) — parent of every view in this proposal
• #625 — Token Authoring Workflow — closest peer; the wizard is one realization of "authoring workflow"

Spec dependencies

• Session primer — primer header and wizard taxonomy fields
• Tool catalog — every TUI view maps to one of these
• Product context — Agent capture behavior — wizard rationale capture
• sdk/core/src/report.rs — diagnostic shape for the validate view
• sdk/cli/src/main.rs — sibling crate sharing core

Ecosystem

• Ratatui · nucleo · similar

---

8. How to engage

• Designer? Used the CLI for token authoring before? Comment on what hurts most in the current flow — Screen 1's "reuse first" banner is the most opinionated decision in this proposal and benefits from concrete pain points.
• SDK contributor? The crate placement (sdk/tui/ vs sdk/tui-core/ + sdk/tui-wizard/) and the DatasetHandle shape are the load-bearing decisions; push back if either looks wrong.
• RFC-C / agent-surface stakeholder? This proposal assumes suggest_token and write_token land per Phase 8 plans. If those plans shift, the wizard's degraded paths (§3.16) may need to grow.
• Want a peek at the demo storyline (§3.17)? Reply if you'd like to be on the M3 review.

[GarthDB]

Pre-adoption housekeeping

Before this RFC moves from Draft to Adopted, a few open questions from Section 6 have been resolved or tracked:

Q6 resolved — crate placement: single sdk/tui/

Going with a single sdk/tui/ crate alongside sdk/cli/ and sdk/core/. The tui-core + tui-wizard split decision is deferred to M3 entry as the RFC already recommends. This unblocks scaffolding without committing to a layout that may or may not be needed.

Phase 8 follow-up issues filed

suggest_token and write_token were deferred out of the Phase 8 epic (#830) but had no tracking issues. Two have now been filed:

• feat(sdk): implement suggest_token operation (Phase 8 follow-up) #975 — feat(sdk): implement suggest_token operation (Phase 8 follow-up)
• feat(sdk): implement write_token operation in sdk/core/ (Phase 8 follow-up) #976 — feat(sdk): implement write_token operation in sdk/core/ (Phase 8 follow-up)

Per the RFC degraded-path language (Section 3.16):

• M0-M3 can ship with query_tokens fallback for Screen 1 if feat(sdk): implement suggest_token operation (Phase 8 follow-up) #975 is not yet ready.
• M4 hard-blocks on feat(sdk): implement write_token operation in sdk/core/ (Phase 8 follow-up) #976. M0-M3 do not.

Q5 still open — theming default

Terminal-native colors with --theme spectrum opt-in vs. Spectrum-flavored by default. Does not block M0 scaffolding but should be settled before M5 polish. Input welcome from anyone demoing on non-macOS terminals.

Questions Q1-Q4 deferred

Per the RFC body, Q1 (scoring threshold), Q2 (foundation wizard), Q3 (persistence), and Q4 (MCP parity) defer to M3+ and do not need to be answered for adoption.

[GarthDB]

Resolving Q5 — theming default

Decision: terminal-native colors by default, with --theme spectrum as an explicit opt-in.

Rationale: the TUI is additive; fighting the user's terminal theme on launch creates friction for the majority of users who have already configured their environment. Spectrum colors are available for those who want a branded experience, but they should never be forced.

This unblocks M5 polish without affecting M0–M4. No code change needed — this is a UX policy captured here and in docs/rfc-coordination.md.

---

Status update: the two hard/soft prerequisites are now closed:

• write_token (hard-blocks M4) — issue feat(sdk): implement write_token operation in sdk/core/ (Phase 8 follow-up) #976 closed, PR feat(sdk): implement write_token operation in sdk/core #978
• suggest_token (soft-blocks Screen 1 reuse-first banner) — issue feat(sdk): implement suggest_token operation (Phase 8 follow-up) #975 closed, PR feat(sdk): implement suggest_token operation in sdk/core #979

M0 (sdk/tui/ crate scaffold) is unblocked.

[GarthDB]

Adopted ✓

All prerequisites are cleared; moving this RFC from Draft to Adopted.

Prerequisites landed:

• suggest_token — issue #975 closed, code in PR #979
• write_token — issue #976 closed, code in PR #978

Open questions resolved:

• Q5 (theming): terminal-native default; --theme spectrum opt-in wired in M5 — no blocker to M0.
• Q6 (crate split): deferred to M3 per §6; single sdk/tui/ crate for M0–M2.

Open questions Q1–Q4 remain open per the RFC body — none are blocking M0.

Tracking infrastructure created:

• Label sdk/tui created (green, matches sdk/* family)
• Epic: #980 — [Epic] TUI & Token Authoring Wizard (RFC #973)
• M0 sub-issue: #981 — feat(sdk): scaffold sdk/tui crate (M0 of RFC #973) (linked as sub-issue under [Epic] TUI & Token Authoring Wizard (RFC #973) #980)

docs/rfc-coordination.md will be updated to Adopted — M0 in progress once the doc commit lands.

[GarthDB]

Q4 closed — MCP start_authoring_session parity ✅

PR #995 lands all eight MCP tools that mirror the wizard's four-screen state machine:

Tool	Wizard screen
start_authoring_session	initialise session on disk
authoring_session_step_intent	Screen 1 — intent + suggestions
authoring_session_step_classification	Screen 2 — layer / schema
authoring_session_step_values	Screen 3 — values / alias
authoring_session_commit	Screen 4 — write to file
authoring_session_cancel	discard session
authoring_session_get	inspect current state
authoring_session_list	enumerate active sessions

State lives in Rust core (sdk/core/src/authoring/session.rs) as atomic JSON files, shared between the TUI and the new CLI subcommand. The MCP tools shell out to authoring-session — same pattern as every other tool in the server.

RFC #973 status after this PR:

• Q3 — wizard draft persistence ✅ (feat(sdk/tui): persist wizard draft across restarts (Q3 of RFC #973) #994)
• Q4 — MCP start_authoring_session parity ✅ (feat(sdk,mcp): add MCP authoring-session tools (RFC #973 Q4) #995)
• Q1 — suggest_token reuse-banner threshold (scoring calibration) — still open
• Q2 — wizard for foundation/structure layers (scope expansion) — still open

[GarthDB]

Q1 closed — PR #996

Calibrated alias_threshold() against packages/tokens/src (1224 tokens):

• Positive matches: 0.60–1.0 (e.g. "neutral content color" → 0.75, "accent content color default" → 1.0)
• Nonsense queries: 0.0
• Chosen threshold: 0.35 (replaces the 0.5 placeholder; overridable via DESIGN_DATA_ALIAS_THRESHOLD)

Also wired the RFC §3.10 reuse-first banner into TUI Screen 1 — it now appears in accent color above the suggestions table when can_alias is true.

[GarthDB]

RFC #973 — Shipped ✓

All milestones and open questions are now resolved. Epic #980 is closed.

Milestones landed:

Milestone	PR
M0 — scaffold sdk/tui/, primer header	#982
M1 — query_tokens end-to-end	#984
M2 — resolve_token, describe_component, validate_usage views	#986
M3 — wizard modal (four screens + diff preview)	#988
M4 — write_token integration	#990
M5 — polish (mouse, help overlay, history, theming)	#992

Open questions resolved:

• Q1 (suggest_token threshold) — calibrated in #997
• Q2 (wizard scope) — standalone naming wizard #999 + find wizard #1001; wizard chassis extraction #1002
• Q3 (state persistence) — draft JSON sidecar in #994
• Q4 (MCP parity) — start_authoring_session and related tools in #995
• Q5 (theming) — terminal-native default, --theme spectrum opt-in, resolved at M5
• Q6 (crate split) — single sdk/tui/ retained per §6 deferral

One item explicitly out of scope for v1 and deferred to a future RFC: a wizard for foundation/structure layer authoring (§5 + §6 Q2). If there's designer demand for that surface, it should open a new discussion rather than reopen this one.

docs/rfc-coordination.md has been updated to reflect the implemented status.