diff --git a/.changeset/reconcile-rfc-coordination-docs.md b/.changeset/reconcile-rfc-coordination-docs.md new file mode 100644 index 000000000..da625aa4d --- /dev/null +++ b/.changeset/reconcile-rfc-coordination-docs.md @@ -0,0 +1,18 @@ +--- +"@adobe/design-data-spec": patch +--- + +Reconcile RFC coordination docs with shipped reality: Phase B, CTR, and guidelines +were undocumented or stale. + +- **packages/design-data-spec/spec/authoring-workflow.md**: flip Phase B (foundation-corpus + write path, token lifecycle ops, mode-set management) from "not yet shipped" to shipped; + clarify `write_component` remains unscheduled. +- **packages/design-data-spec/spec/agent-surface.md**: promote `write_token` from RECOMMENDED + to NORMATIVE (MUST), matching the Phase B promotion now reflected in authoring-workflow.md. +- **docs/rfc-coordination.md**: add RFC-E (Component/Token Relationships) and RFC-F + (Guidelines/Phase 10) rows, a #1324 draft-RFC row, reference 6 previously-orphaned + spec files, and refresh #806/#623/#625/#832 with rules and PRs shipped since the + last update. +- **docs/token-studio-sunset.md**: mark Phase 1 (foundation-corpus write target) done, + unblocking Phase 2. diff --git a/docs/rfc-coordination.md b/docs/rfc-coordination.md index 563e966de..5fe01ea7b 100644 --- a/docs/rfc-coordination.md +++ b/docs/rfc-coordination.md @@ -6,29 +6,32 @@ ## RFC family -| RFC | Title | Authoritative spec | Status | Open questions | -| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [#714](https://github.com/adobe/spectrum-design-data/discussions/714) | Spectrum Design Data Specification (umbrella) | [`spec/index.md`](../packages/design-data-spec/spec/index.md) | In progress — Phases 0–3 and 6–9 implemented (RFC-A epic [#828](https://github.com/adobe/spectrum-design-data/issues/828), RFC-B epic [#829](https://github.com/adobe/spectrum-design-data/issues/829), RFC-C epic [#830](https://github.com/adobe/spectrum-design-data/issues/830), RFC-D epic [#831](https://github.com/adobe/spectrum-design-data/issues/831)); Phase 4 authoring tooling now covered by RFC [#973](https://github.com/adobe/spectrum-design-data/issues/973) (TUI + MCP shipped — PRs [#999](https://github.com/adobe/spectrum-design-data/pull/999), [#1001](https://github.com/adobe/spectrum-design-data/pull/1001), [#995](https://github.com/adobe/spectrum-design-data/pull/995)); output generators still in progress; Phase 5 (platform SDKs) tracked under epic [#731](https://github.com/adobe/spectrum-design-data/issues/731) | ~~Product-level overrides~~ — resolved: SPEC-032 + cascade layer enforcement (PR [#914](https://github.com/adobe/spectrum-design-data/issues/914)); ~~component anatomy audit~~ — resolved: anatomy-terms expanded 43→122 (PR [#915](https://github.com/adobe/spectrum-design-data/issues/915)); ~~registry split~~ — resolved: three-registry boundary formalized in [`spec/registry.md`](../packages/design-data-spec/spec/registry.md), single-package strategy adopted (PR [#918](https://github.com/adobe/spectrum-design-data/pull/918)); ~~events and slots in or out of v1 of Component Contract~~ — resolved: slots included in component-format.md (SPEC-021); events deferred per cross-platform audit ([`audits/events.audit.md`](../packages/design-data-spec/audits/events.audit.md)) — naming model not cross-platform stable, taxonomy work prerequisite | -| [#715](https://github.com/adobe/spectrum-design-data/discussions/715) | Distributed Design Data Architecture | [`spec/manifest.md`](../packages/design-data-spec/spec/manifest.md), [`spec/cascade.md`](../packages/design-data-spec/spec/cascade.md) | In progress — manifest and cascade are normative; SPEC-039 lifted the query-notation deferral; Phase 5 cross-repo upgrade automation still open under epic [#731](https://github.com/adobe/spectrum-design-data/issues/731); this layering model was extended by RFC-B (foundation accessibility, now implemented under epic [#829](https://github.com/adobe/spectrum-design-data/issues/829)) | ~~Schema for manifest `include`/`exclude` queries (notation defined in [`spec/query.md`](../packages/design-data-spec/spec/query.md), normative manifest use deferred)~~ — resolved: SPEC-039 lifts the deferred clause; entries are now validated against the `spec/query.md` grammar at Layer 2; product-level overrides in the **distributed** context (single-dataset type-compat resolved by SPEC-032 / PR [#914](https://github.com/adobe/spectrum-design-data/pull/914); cross-repo product manifest shape and upgrade timeline still open); platform-private experimental tokens policy | -| [#806](https://github.com/adobe/spectrum-design-data/discussions/806) | Token Taxonomy, Vocabulary, and Formatting | [`spec/taxonomy.md`](../packages/design-data-spec/spec/taxonomy.md), [`spec/token-format.md`](../packages/design-data-spec/spec/token-format.md) | Implemented — three-layer decomposition, name-object restructuring, and anatomy/objects distinction merged ([PR #807](https://github.com/adobe/spectrum-design-data/pull/807)); all open questions resolved (PRs [#915](https://github.com/adobe/spectrum-design-data/pull/915), [#927](https://github.com/adobe/spectrum-design-data/pull/927), [#941](https://github.com/adobe/spectrum-design-data/issues/941), [#942](https://github.com/adobe/spectrum-design-data/issues/942), [#943](https://github.com/adobe/spectrum-design-data/issues/943), [#938](https://github.com/adobe/spectrum-design-data/issues/938)); token-names sidecar package extracted ([PR #972](https://github.com/adobe/spectrum-design-data/pull/972)) | ~~Anatomy audit cleanup scope (133 S2 terms)~~ — resolved: anatomy-terms expanded 43→122 (PRs [#915](https://github.com/adobe/spectrum-design-data/pull/915), [#927](https://github.com/adobe/spectrum-design-data/pull/927)); ~~`property` field migration path~~ — resolved: normative migration policy + SPEC-017 `2.0.0` escalation schedule + `property-terms.json` registry added in [#941](https://github.com/adobe/spectrum-design-data/issues/941); ~~future taxonomies (color/typography/motion)~~ — resolved: color, typography, and motion taxonomies added to `spec/taxonomy.md` with scoped fields under `fields/`, registries under `packages/design-system-registry/registry/`, and SPEC-042 (`field-scope-violation`) + SPEC-043 (`domain-required-fields`) enforcement ([#942](https://github.com/adobe/spectrum-design-data/issues/942)); ~~platform mode-set restriction behavior (visibility vs. fallback)~~ — resolved: visibility filter at resolve time (cascade step 0) + SPEC-041 coverage rule; restrictions declared in platform manifest `modeSetRestrictions` field ([#943](https://github.com/adobe/spectrum-design-data/issues/943)); ~~cross-validation of `component`/`variant`/`state`/`anatomy` field values against component declarations~~ — resolved: SPEC-018/019/020/022 cover existence checks; SPEC-040 (`component-option-field-valid`, Warning) generalises value-checking to all declared `options.*` fields beyond `variant` ([#938](https://github.com/adobe/spectrum-design-data/issues/938)) | -| [#832](https://github.com/adobe/spectrum-design-data/discussions/832) | Component Contract in Design Data Spec | [`spec/component-format.md`](../packages/design-data-spec/spec/component-format.md), [`spec/anatomy-format.md`](../packages/design-data-spec/spec/anatomy-format.md), [`spec/state-model.md`](../packages/design-data-spec/spec/state-model.md) | Implemented — Phases 6.0–6.7 complete ([PR #849](https://github.com/adobe/spectrum-design-data/pull/849)–[#853](https://github.com/adobe/spectrum-design-data/pull/853), [#855](https://github.com/adobe/spectrum-design-data/pull/855), [#857](https://github.com/adobe/spectrum-design-data/pull/857), [#858](https://github.com/adobe/spectrum-design-data/pull/858)) | ~~Component-level deprecation cascade to dependent tokens~~ — resolved: SPEC-036 advisory rule warns when a non-deprecated token references a deprecated component; ~~anatomy-part, state, and option-enum deprecation cascade to dependent tokens~~ — resolved: SPEC-037 advisory rule (schemas extended to allow `lifecycle` on anatomy/state sub-entities and `lifecycle` per value in option descriptor `values` array); ~~deprecatedEnumValues key-validation gap~~ — resolved: SPEC-038 structural change replaced `enum` + `deprecatedEnumValues` sidecar with a unified `values: [{value, lifecycle?}]` array, making drift impossible | -| [#735](https://github.com/adobe/spectrum-design-data/discussions/735) | Spec Versioning and Evolution | [`spec/evolution.md`](../packages/design-data-spec/spec/evolution.md) | Implemented (SemVer policy, change classification, two-minor-version migration window, dual-format coexistence) | Schema `$id` / URI strategy (`v0` paths in use de facto, formal policy pending); SDK `--spec-version` behavior; cross-repo upgrade-timeline automation; ~~component-level deprecation cascading to dependent tokens~~ — resolved: SPEC-036 advisory rule | -| [#661](https://github.com/adobe/spectrum-design-data/discussions/661) | Spectrum Design System Glossary | `@adobe/design-system-registry` (not in spec/), [`spec/registry.md`](../packages/design-data-spec/spec/registry.md) | Phases 0–2 complete; three-registry boundary formalized in `spec/registry.md` (anatomy-terms, token-objects, categories); single-package strategy adopted | Maintenance & governance cadence; prioritization of new collections; registry ↔ token enum sync (three-registry split from [#806](https://github.com/adobe/spectrum-design-data/discussions/806) now landed — SPEC-009 covers `object` field advisory sync; ~~`category` field validation against categories.json is an open gap~~ — resolved: SPEC-034 advisory rule + schema loosened to free-form string; `data-visualization` alias removed; ~~anatomy part `name` field validation against anatomy-terms.json is an open gap~~ — resolved: SPEC-035 advisory rule) | -| [#646](https://github.com/adobe/spectrum-design-data/discussions/646) | Token Schema Structure and Validation | [`spec/token-format.md`](../packages/design-data-spec/spec/token-format.md), [`spec/cascade.md`](../packages/design-data-spec/spec/cascade.md) | Historical reference — original analytical model; spec is now authoritative | n/a (open questions migrated to spec or to other RFCs in this family) | -| [#623](https://github.com/adobe/spectrum-design-data/discussions/623) | Token Lifecycle Metadata (from RFC [#623](https://github.com/adobe/spectrum-design-data/issues/623) "Token Deprecation and Consolidation") | [`spec/token-format.md`](../packages/design-data-spec/spec/token-format.md) (lifecycle table), [`spec/evolution.md`](../packages/design-data-spec/spec/evolution.md) | Implemented ([PR #793](https://github.com/adobe/spectrum-design-data/pull/793)) | Cascade-specific token lifecycle merge rules across foundation + platform layers (TBD in tooling) | -| [#625](https://github.com/adobe/spectrum-design-data/discussions/625) | Token Authoring Workflow | [`spec/authoring-workflow.md`](../packages/design-data-spec/spec/authoring-workflow.md) — ~~*none yet*~~ — resolved: Phase A backbone landed | Partially superseded by RFC [#973](https://github.com/adobe/spectrum-design-data/discussions/973) (TUI + MCP tooling shipped; epic [#980](https://github.com/adobe/spectrum-design-data/issues/980) closed) — **Phase A spec ratification complete**: authoring-workflow backbone (A1), per-category authoring contracts (A2), SPEC-043 severity schedule (A3), output-generator conformance fixtures (A4), and agent-surface promotion alignment (A5) all landed; foundation-corpus write-path tooling (Phase B) is the next open gate | Figma sync direction; multi-user collaboration; permissions model; foundation-corpus write-path redirect (Phase B scheduled — see [`spec/authoring-workflow.md#scheduled-promotion`](../packages/design-data-spec/spec/authoring-workflow.md#scheduled-promotion)) | -| [#973](https://github.com/adobe/spectrum-design-data/discussions/973) | Interactive TUI & Token Authoring Wizard | `sdk/tui/` (`design-data-tui` crate); consumes [Agent Surface spec](../packages/design-data-spec/spec/agent-surface.md) | Implemented — M0–M5 shipped (epic [#980](https://github.com/adobe/spectrum-design-data/issues/980) closed) | ~~`suggest_token` scoring threshold for "reuse first" banner~~ — resolved: threshold calibrated against real Spectrum data in PR [#997](https://github.com/adobe/spectrum-design-data/pull/997); ~~wizard scope for foundation/structure layers~~ — resolved: standalone naming wizard ([#999](https://github.com/adobe/spectrum-design-data/pull/999)) and find wizard ([#1001](https://github.com/adobe/spectrum-design-data/pull/1001)) shipped; foundation/structure layer explicitly deferred to a future RFC (out of scope per §5); ~~wizard state persistence across process restarts~~ — resolved: draft persistence via JSON sidecar landed in PR [#994](https://github.com/adobe/spectrum-design-data/pull/994); ~~MCP parity (`start_authoring_session` tool for agents)~~ — resolved: MCP authoring-session tools landed in PR [#995](https://github.com/adobe/spectrum-design-data/pull/995); ~~theming (terminal-native vs. `--theme spectrum`)~~ — resolved: terminal-native default, `--theme spectrum` opt-in; ~~crate split (`sdk/tui/` vs. `sdk/tui-core/` + `sdk/tui-wizard/`)~~ — resolved: single `sdk/tui/` crate retained | -| [#624](https://github.com/adobe/spectrum-design-data/discussions/624) | Token Structure (historical multi-platform) | n/a | Closed — superseded by [#715](https://github.com/adobe/spectrum-design-data/issues/715) | n/a | -| [#626](https://github.com/adobe/spectrum-design-data/discussions/626) | Design Token Sourcemaps | n/a | Deferred — future traceability layer atop UUIDs | n/a | -| [#627](https://github.com/adobe/spectrum-design-data/discussions/627) | DTCG Format Output | n/a | Deferred — should consume resolved cascade when implemented | n/a | -| [#642](https://github.com/adobe/spectrum-design-data/discussions/642) | Component Schema Feedback Automation Pipeline | n/a | Deferred — backlog | n/a | -| RFC-C (no discussion yet) | Agent-Readable Surface (MCP, CLI, Skill) | [`spec/agent-surface.md`](../packages/design-data-spec/spec/agent-surface.md) | Implemented — Phase 8 complete (epic [#830](https://github.com/adobe/spectrum-design-data/issues/830)). CLI subcommands ([#865](https://github.com/adobe/spectrum-design-data/issues/865) primer, [#866](https://github.com/adobe/spectrum-design-data/issues/866) component), MCP server ([#867](https://github.com/adobe/spectrum-design-data/issues/867), `tools/design-data-agent-mcp/`), Claude Code Skill packaging ([#868](https://github.com/adobe/spectrum-design-data/issues/868)) all shipped. | ~~Reference MCP placement~~ — resolved: `tools/design-data-agent-mcp/`; ~~`suggest_token` ranking~~ — resolved: not shipped in v1; guarantees for non-Spectrum manifests during the Mercury/Protopack joint spike | -| RFC-B (no discussion yet) | Foundation Accessibility Semantics | [`spec/accessibility.md`](../packages/design-data-spec/spec/accessibility.md), [`spec/accessibility-adapters.md`](../packages/design-data-spec/spec/accessibility-adapters.md) | Implemented — Phase 7 complete (epic [#829](https://github.com/adobe/spectrum-design-data/issues/829)). Normative vocabulary ([#882](https://github.com/adobe/spectrum-design-data/issues/882)), adapter contracts ([#883](https://github.com/adobe/spectrum-design-data/issues/883)), schema wiring ([#884](https://github.com/adobe/spectrum-design-data/issues/884)), SPEC-030/031 + conformance fixtures ([#885](https://github.com/adobe/spectrum-design-data/issues/885), [#894](https://github.com/adobe/spectrum-design-data/issues/894)) all shipped. | ~~[#892](https://github.com/adobe/spectrum-design-data/issues/892) — expand canonical role vocabulary~~ — resolved: added progressbar, meter, grid, listitem, group to canonical vocabulary; meter/progress-*/table/*-group components updated | -| RFC-D (no discussion yet) | Document Blocks for Prose & Agent Context | [`spec/document-blocks.md`](../packages/design-data-spec/spec/document-blocks.md) | Implemented — Phase 9 complete (epic [#831](https://github.com/adobe/spectrum-design-data/issues/831)). SPEC-028/029 in rule catalog; conformance fixtures [#894](https://github.com/adobe/spectrum-design-data/issues/894). | n/a | +| RFC | Title | Authoritative spec | Status | Open questions | +| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [#714](https://github.com/adobe/spectrum-design-data/discussions/714) | Spectrum Design Data Specification (umbrella) | [`spec/index.md`](../packages/design-data-spec/spec/index.md), [`spec/diff.md`](../packages/design-data-spec/spec/diff.md) (Phase 3 diff + query) | In progress — Phases 0–3 and 6–9 implemented (RFC-A epic [#828](https://github.com/adobe/spectrum-design-data/issues/828), RFC-B epic [#829](https://github.com/adobe/spectrum-design-data/issues/829), RFC-C epic [#830](https://github.com/adobe/spectrum-design-data/issues/830), RFC-D epic [#831](https://github.com/adobe/spectrum-design-data/issues/831)); Phase 4 authoring tooling now covered by RFC [#973](https://github.com/adobe/spectrum-design-data/issues/973) (TUI + MCP shipped — PRs [#999](https://github.com/adobe/spectrum-design-data/pull/999), [#1001](https://github.com/adobe/spectrum-design-data/pull/1001), [#995](https://github.com/adobe/spectrum-design-data/pull/995)); output generators still in progress; Phase 5 (platform SDKs) tracked under epic [#731](https://github.com/adobe/spectrum-design-data/issues/731) | ~~Product-level overrides~~ — resolved: SPEC-032 + cascade layer enforcement (PR [#914](https://github.com/adobe/spectrum-design-data/issues/914)); ~~component anatomy audit~~ — resolved: anatomy-terms expanded 43→122 (PR [#915](https://github.com/adobe/spectrum-design-data/issues/915)); ~~registry split~~ — resolved: three-registry boundary formalized in [`spec/registry.md`](../packages/design-data-spec/spec/registry.md), single-package strategy adopted (PR [#918](https://github.com/adobe/spectrum-design-data/pull/918)); ~~events and slots in or out of v1 of Component Contract~~ — resolved: slots included in component-format.md (SPEC-021); events deferred per cross-platform audit ([`audits/events.audit.md`](../packages/design-data-spec/audits/events.audit.md)) — naming model not cross-platform stable, taxonomy work prerequisite | +| [#715](https://github.com/adobe/spectrum-design-data/discussions/715) | Distributed Design Data Architecture | [`spec/manifest.md`](../packages/design-data-spec/spec/manifest.md), [`spec/cascade.md`](../packages/design-data-spec/spec/cascade.md), [`spec/dataset-layout.md`](../packages/design-data-spec/spec/dataset-layout.md) (SPEC-044 `dataset-structure`), [`spec/mode-sets.md`](../packages/design-data-spec/spec/mode-sets.md), [`spec/product-context.md`](../packages/design-data-spec/spec/product-context.md) | In progress — manifest and cascade are normative; SPEC-039 lifted the query-notation deferral; Phase 5 cross-repo upgrade automation still open under epic [#731](https://github.com/adobe/spectrum-design-data/issues/731); this layering model was extended by RFC-B (foundation accessibility, now implemented under epic [#829](https://github.com/adobe/spectrum-design-data/issues/829)) | ~~Schema for manifest `include`/`exclude` queries (notation defined in [`spec/query.md`](../packages/design-data-spec/spec/query.md), normative manifest use deferred)~~ — resolved: SPEC-039 lifts the deferred clause; entries are now validated against the `spec/query.md` grammar at Layer 2; product-level overrides in the **distributed** context (single-dataset type-compat resolved by SPEC-032 / PR [#914](https://github.com/adobe/spectrum-design-data/pull/914); cross-repo product manifest shape and upgrade timeline still open); platform-private experimental tokens policy | +| [#806](https://github.com/adobe/spectrum-design-data/discussions/806) | Token Taxonomy, Vocabulary, and Formatting | [`spec/taxonomy.md`](../packages/design-data-spec/spec/taxonomy.md), [`spec/token-format.md`](../packages/design-data-spec/spec/token-format.md) | Implemented — three-layer decomposition, name-object restructuring, and anatomy/objects distinction merged ([PR #807](https://github.com/adobe/spectrum-design-data/pull/807)); all open questions resolved (PRs [#915](https://github.com/adobe/spectrum-design-data/pull/915), [#927](https://github.com/adobe/spectrum-design-data/pull/927), [#941](https://github.com/adobe/spectrum-design-data/issues/941), [#942](https://github.com/adobe/spectrum-design-data/issues/942), [#943](https://github.com/adobe/spectrum-design-data/issues/943), [#938](https://github.com/adobe/spectrum-design-data/issues/938)); token-names sidecar package extracted ([PR #972](https://github.com/adobe/spectrum-design-data/pull/972)); space-between endpoint validation added (SPEC-047, [#1216](https://github.com/adobe/spectrum-design-data/pull/1216)); anatomy/registry cross-checks added (SPEC-048 `anatomy-contains-resolves` [#1223](https://github.com/adobe/spectrum-design-data/pull/1223), SPEC-049 `anatomy-in-registry` [#1289](https://github.com/adobe/spectrum-design-data/pull/1289)); property decomposition completeness added (SPEC-050, [#1280](https://github.com/adobe/spectrum-design-data/pull/1280)); compound states restructured `name.state` string → ordered array, a breaking change (`design-data-spec` 3.0.0, [#1302](https://github.com/adobe/spectrum-design-data/pull/1302), see [proposal 006](../docs/proposals/006-compound-states-as-array.md)) | ~~Anatomy audit cleanup scope (133 S2 terms)~~ — resolved: anatomy-terms expanded 43→122 (PRs [#915](https://github.com/adobe/spectrum-design-data/pull/915), [#927](https://github.com/adobe/spectrum-design-data/pull/927)); ~~`property` field migration path~~ — resolved: normative migration policy + SPEC-017 `2.0.0` escalation schedule + `property-terms.json` registry added in [#941](https://github.com/adobe/spectrum-design-data/issues/941); ~~future taxonomies (color/typography/motion)~~ — resolved: color, typography, and motion taxonomies added to `spec/taxonomy.md` with scoped fields under `fields/`, registries under `packages/design-system-registry/registry/`, and SPEC-042 (`field-scope-violation`) + SPEC-043 (`domain-required-fields`) enforcement ([#942](https://github.com/adobe/spectrum-design-data/issues/942)); ~~platform mode-set restriction behavior (visibility vs. fallback)~~ — resolved: visibility filter at resolve time (cascade step 0) + SPEC-041 coverage rule; restrictions declared in platform manifest `modeSetRestrictions` field ([#943](https://github.com/adobe/spectrum-design-data/issues/943)); ~~cross-validation of `component`/`variant`/`state`/`anatomy` field values against component declarations~~ — resolved: SPEC-018/019/020/022 cover existence checks; SPEC-040 (`component-option-field-valid`, Warning) generalises value-checking to all declared `options.*` fields beyond `variant` ([#938](https://github.com/adobe/spectrum-design-data/issues/938)) | +| [#832](https://github.com/adobe/spectrum-design-data/discussions/832) | Component Contract in Design Data Spec | [`spec/component-format.md`](../packages/design-data-spec/spec/component-format.md), [`spec/anatomy-format.md`](../packages/design-data-spec/spec/anatomy-format.md), [`spec/state-model.md`](../packages/design-data-spec/spec/state-model.md) | Implemented — Phases 6.0–6.7 complete ([PR #849](https://github.com/adobe/spectrum-design-data/pull/849)–[#853](https://github.com/adobe/spectrum-design-data/pull/853), [#855](https://github.com/adobe/spectrum-design-data/pull/855), [#857](https://github.com/adobe/spectrum-design-data/pull/857), [#858](https://github.com/adobe/spectrum-design-data/pull/858)). Per-component `tokenBindings` are now superseded going forward by RFC-E's Component/Token Relationships (CTR); `tokenBindings`/`componentBindings` remain valid in the schema during an interim migration window (removal deferred). | ~~Component-level deprecation cascade to dependent tokens~~ — resolved: SPEC-036 advisory rule warns when a non-deprecated token references a deprecated component; ~~anatomy-part, state, and option-enum deprecation cascade to dependent tokens~~ — resolved: SPEC-037 advisory rule (schemas extended to allow `lifecycle` on anatomy/state sub-entities and `lifecycle` per value in option descriptor `values` array); ~~deprecatedEnumValues key-validation gap~~ — resolved: SPEC-038 structural change replaced `enum` + `deprecatedEnumValues` sidecar with a unified `values: [{value, lifecycle?}]` array, making drift impossible | +| [#735](https://github.com/adobe/spectrum-design-data/discussions/735) | Spec Versioning and Evolution | [`spec/evolution.md`](../packages/design-data-spec/spec/evolution.md) | Implemented (SemVer policy, change classification, two-minor-version migration window, dual-format coexistence) | Schema `$id` / URI strategy (`v0` paths in use de facto, formal policy pending); SDK `--spec-version` behavior; cross-repo upgrade-timeline automation; ~~component-level deprecation cascading to dependent tokens~~ — resolved: SPEC-036 advisory rule | +| [#661](https://github.com/adobe/spectrum-design-data/discussions/661) | Spectrum Design System Glossary | `@adobe/design-system-registry` (not in spec/), [`spec/registry.md`](../packages/design-data-spec/spec/registry.md) | Phases 0–2 complete; three-registry boundary formalized in `spec/registry.md` (anatomy-terms, token-objects, categories); single-package strategy adopted | Maintenance & governance cadence; prioritization of new collections; registry ↔ token enum sync (three-registry split from [#806](https://github.com/adobe/spectrum-design-data/discussions/806) now landed — SPEC-009 covers `object` field advisory sync; ~~`category` field validation against categories.json is an open gap~~ — resolved: SPEC-034 advisory rule + schema loosened to free-form string; `data-visualization` alias removed; ~~anatomy part `name` field validation against anatomy-terms.json is an open gap~~ — resolved: SPEC-035 advisory rule) | +| [#646](https://github.com/adobe/spectrum-design-data/discussions/646) | Token Schema Structure and Validation | [`spec/token-format.md`](../packages/design-data-spec/spec/token-format.md), [`spec/cascade.md`](../packages/design-data-spec/spec/cascade.md) | Historical reference — original analytical model; spec is now authoritative | n/a (open questions migrated to spec or to other RFCs in this family) | +| [#623](https://github.com/adobe/spectrum-design-data/discussions/623) | Token Lifecycle Metadata (from RFC [#623](https://github.com/adobe/spectrum-design-data/issues/623) "Token Deprecation and Consolidation") | [`spec/token-format.md`](../packages/design-data-spec/spec/token-format.md) (lifecycle table), [`spec/evolution.md`](../packages/design-data-spec/spec/evolution.md) | Implemented ([PR #793](https://github.com/adobe/spectrum-design-data/pull/793)); restructured into a nested `lifecycle` object as a breaking change — `deprecated` → `lifecycle.deprecatedIn` (`design-data` 2.0.0, [#1325](https://github.com/adobe/spectrum-design-data/pull/1325), 1,323 tokens migrated) | Cascade-specific token lifecycle merge rules across foundation + platform layers (TBD in tooling) | +| [#625](https://github.com/adobe/spectrum-design-data/discussions/625) | Token Authoring Workflow | [`spec/authoring-workflow.md`](../packages/design-data-spec/spec/authoring-workflow.md) — ~~*none yet*~~ — resolved: Phase A backbone landed | Partially superseded by RFC [#973](https://github.com/adobe/spectrum-design-data/discussions/973) (TUI + MCP tooling shipped; epic [#980](https://github.com/adobe/spectrum-design-data/issues/980) closed) — **Phase A spec ratification complete**: authoring-workflow backbone (A1), per-category authoring contracts (A2), SPEC-043 severity schedule (A3), output-generator conformance fixtures (A4), and agent-surface promotion alignment (A5) all landed; **Phase B core authoring engine shipped** (epic `spectrum-design-data-122` closed): cascade write path now targets `packages/design-data/tokens/*.tokens.json` directly (`design_data_core::write::cascade_target_filename`, wired through CLI/TUI/MCP), plus edit/deprecate/rename/alias-rewire/mode-set operations and catalog-aware classification | Figma sync direction — partially resolved: `figma audit`/`export` subcommands with name-mapping override ([#1319](https://github.com/adobe/spectrum-design-data/issues/1319), [#1321](https://github.com/adobe/spectrum-design-data/issues/1321), [#1322](https://github.com/adobe/spectrum-design-data/issues/1322)); multi-user collaboration; permissions model; ~~foundation-corpus write-path redirect (Phase B)~~ — resolved, see Status column and [`spec/authoring-workflow.md#scheduled-promotion`](../packages/design-data-spec/spec/authoring-workflow.md#scheduled-promotion) | +| [#973](https://github.com/adobe/spectrum-design-data/discussions/973) | Interactive TUI & Token Authoring Wizard | `sdk/tui/` (`design-data-tui` crate); consumes [Agent Surface spec](../packages/design-data-spec/spec/agent-surface.md) | Implemented — M0–M5 shipped (epic [#980](https://github.com/adobe/spectrum-design-data/issues/980) closed) | ~~`suggest_token` scoring threshold for "reuse first" banner~~ — resolved: threshold calibrated against real Spectrum data in PR [#997](https://github.com/adobe/spectrum-design-data/pull/997); ~~wizard scope for foundation/structure layers~~ — resolved: standalone naming wizard ([#999](https://github.com/adobe/spectrum-design-data/pull/999)) and find wizard ([#1001](https://github.com/adobe/spectrum-design-data/pull/1001)) shipped; foundation/structure layer explicitly deferred to a future RFC (out of scope per §5); ~~wizard state persistence across process restarts~~ — resolved: draft persistence via JSON sidecar landed in PR [#994](https://github.com/adobe/spectrum-design-data/pull/994); ~~MCP parity (`start_authoring_session` tool for agents)~~ — resolved: MCP authoring-session tools landed in PR [#995](https://github.com/adobe/spectrum-design-data/pull/995); ~~theming (terminal-native vs. `--theme spectrum`)~~ — resolved: terminal-native default, `--theme spectrum` opt-in; ~~crate split (`sdk/tui/` vs. `sdk/tui-core/` + `sdk/tui-wizard/`)~~ — resolved: single `sdk/tui/` crate retained | +| [#624](https://github.com/adobe/spectrum-design-data/discussions/624) | Token Structure (historical multi-platform) | n/a | Closed — superseded by [#715](https://github.com/adobe/spectrum-design-data/issues/715) | n/a | +| [#626](https://github.com/adobe/spectrum-design-data/discussions/626) | Design Token Sourcemaps | n/a | Deferred — future traceability layer atop UUIDs | n/a | +| [#627](https://github.com/adobe/spectrum-design-data/discussions/627) | DTCG Format Output | n/a | Deferred — should consume resolved cascade when implemented | n/a | +| [#642](https://github.com/adobe/spectrum-design-data/discussions/642) | Component Schema Feedback Automation Pipeline | n/a | Deferred — backlog | n/a | +| RFC-C (no discussion yet) | Agent-Readable Surface (MCP, CLI, Skill) | [`spec/agent-surface.md`](../packages/design-data-spec/spec/agent-surface.md) | Implemented — Phase 8 complete (epic [#830](https://github.com/adobe/spectrum-design-data/issues/830)). CLI subcommands ([#865](https://github.com/adobe/spectrum-design-data/issues/865) primer, [#866](https://github.com/adobe/spectrum-design-data/issues/866) component), MCP server ([#867](https://github.com/adobe/spectrum-design-data/issues/867), `tools/design-data-agent-mcp/`), Claude Code Skill packaging ([#868](https://github.com/adobe/spectrum-design-data/issues/868)) all shipped. | ~~Reference MCP placement~~ — resolved: `tools/design-data-agent-mcp/`; ~~`suggest_token` ranking~~ — resolved: not shipped in v1; guarantees for non-Spectrum manifests during the Mercury/Protopack joint spike | +| RFC-B (no discussion yet) | Foundation Accessibility Semantics | [`spec/accessibility.md`](../packages/design-data-spec/spec/accessibility.md), [`spec/accessibility-adapters.md`](../packages/design-data-spec/spec/accessibility-adapters.md) | Implemented — Phase 7 complete (epic [#829](https://github.com/adobe/spectrum-design-data/issues/829)). Normative vocabulary ([#882](https://github.com/adobe/spectrum-design-data/issues/882)), adapter contracts ([#883](https://github.com/adobe/spectrum-design-data/issues/883)), schema wiring ([#884](https://github.com/adobe/spectrum-design-data/issues/884)), SPEC-030/031 + conformance fixtures ([#885](https://github.com/adobe/spectrum-design-data/issues/885), [#894](https://github.com/adobe/spectrum-design-data/issues/894)) all shipped. | ~~[#892](https://github.com/adobe/spectrum-design-data/issues/892) — expand canonical role vocabulary~~ — resolved: added progressbar, meter, grid, listitem, group to canonical vocabulary; meter/progress-*/table/*-group components updated | +| RFC-D (no discussion yet) | Document Blocks for Prose & Agent Context | [`spec/document-blocks.md`](../packages/design-data-spec/spec/document-blocks.md) | Implemented — Phase 9 complete (epic [#831](https://github.com/adobe/spectrum-design-data/issues/831)). SPEC-028/029 in rule catalog; conformance fixtures [#894](https://github.com/adobe/spectrum-design-data/issues/894). | n/a | +| RFC-E (no discussion yet) | Component/Token Relationships (CTR) | [`spec/relationship-format.md`](../packages/design-data-spec/spec/relationship-format.md), [`schemas/relationship.schema.json`](../packages/design-data-spec/schemas/relationship.schema.json) | Implemented — CTR foundation shipped in `design-data-spec` 3.2.0 ([#1327](https://github.com/adobe/spectrum-design-data/pull/1327), rules SPEC-051–057; conformance fixtures [#1331](https://github.com/adobe/spectrum-design-data/pull/1331)). Corpus data migrated onto CTRs in `design-data` 2.1.0 ([#1330](https://github.com/adobe/spectrum-design-data/pull/1330); legacy-key reconstruction [#1329](https://github.com/adobe/spectrum-design-data/pull/1329)); dangling legacy `tokenBindings` (SPEC-027) removed in 2.1.1 ([#1333](https://github.com/adobe/spectrum-design-data/pull/1333)). A CTR unifies component-side `tokenBindings` and token-side name-object scope fields into one anonymous, scope-carrying entity under `relationships/*.json`. Supersedes the RFC-A/[#832](https://github.com/adobe/spectrum-design-data/issues/832) `tokenBindings` mechanism going forward. | `tokenBindings`/`componentBindings` remain valid in the schema during an interim migration window — eventual removal is deferred to a future migration phase (not yet scheduled). | +| RFC-F (no discussion yet) | Guidelines (prose guidance atop document blocks) | [`spec/guideline-format.md`](../packages/design-data-spec/spec/guideline-format.md), [`schemas/guideline.schema.json`](../packages/design-data-spec/schemas/guideline.schema.json) | Implemented — Phase 10 complete. Guideline entity schema + rules (beads `459`, Phase 1) and `guidelines/*.json` transformer (beads `ek4`, Phase 2) both shipped. Rules SPEC-045 (`guideline-missing-purpose`), SPEC-046 (`guideline-related-resolves`) in rule catalog. Depends on RFC-D document blocks for its body shape. | n/a | +| [#1324](https://github.com/adobe/spectrum-design-data/discussions/1324) | Platform Coverage Metrics via Manifest Adoption | n/a | Draft — relates to beads epic `pct` (per-platform token usage baselines) and `v01` (metrics reporting & partner analysis) | n/a | See also: [Token Studio sunset roadmap](token-studio-sunset.md) — tracks retiring the -Token Studio inbound sync (RFC #625) in favor of the native authoring-session + Figma -export path, gated on the Phase B foundation-corpus write-path redirect. +Token Studio inbound sync (RFC [#625](https://github.com/adobe/spectrum-design-data/issues/625)) in favor of the native authoring-session + Figma +export path; the Phase B foundation-corpus write-path redirect that gated this has shipped, unblocking the roadmap's later phases. ## Previously planned RFCs (now implemented) @@ -50,11 +53,12 @@ The umbrella RFC ([#714](https://github.com/adobe/spectrum-design-data/discussio * **Phase 1** — Token format, taxonomy, name object, lifecycle metadata * **Phase 2** — Cascade resolution + dimensions * **Phase 3** — Diff + query -* **Phase 4** — Output generators, authoring tooling — **Phase A spec ratification complete**: authoring-workflow spec ([`spec/authoring-workflow.md`](../packages/design-data-spec/spec/authoring-workflow.md)), per-category contracts, SPEC-043 severity schedule, output-generator conformance fixtures, and agent-surface promotion alignment all landed (A1–A5); foundation-corpus write-path tooling deferred to Phase B +* **Phase 4** — Output generators, authoring tooling — **Phase A spec ratification complete**: authoring-workflow spec ([`spec/authoring-workflow.md`](../packages/design-data-spec/spec/authoring-workflow.md)), per-category contracts, SPEC-043 severity schedule, output-generator conformance fixtures, and agent-surface promotion alignment all landed (A1–A5); Phase B core authoring engine (foundation-corpus write-path redirect + lifecycle ops + catalog-aware classification) shipped (epic `spectrum-design-data-122` closed) * **Phase 5** — Distributed manifests across platform repos, upgrade automation * **Phase 6** — Component contract: options + anatomy + state model + token binding declarations — Phase 6.7 ([PR #858](https://github.com/adobe/spectrum-design-data/pull/858)) (implemented; scoped under [RFC-A #832](https://github.com/adobe/spectrum-design-data/discussions/832)) * **Phase 7** — Foundation accessibility semantics (implemented under RFC-B; epic [#829](https://github.com/adobe/spectrum-design-data/issues/829)) * **Phase 8** — Agent-readable surface via [`spec/agent-surface.md`](../packages/design-data-spec/spec/agent-surface.md) (implemented under RFC-C; epic [#830](https://github.com/adobe/spectrum-design-data/issues/830)) * **Phase 9** — Document blocks for prose & agent context (implemented under RFC-D; epic [#831](https://github.com/adobe/spectrum-design-data/issues/831)) +* **Phase 10** — Guidelines: prose guidance entity atop document blocks (implemented under RFC-F; [`spec/guideline-format.md`](../packages/design-data-spec/spec/guideline-format.md), rules SPEC-045/046; beads `459` schema+rules, \[`ek4`] transformer) Tracked on the [project board](https://github.com/orgs/adobe/projects/89). diff --git a/docs/token-studio-sunset.md b/docs/token-studio-sunset.md index 4799a0851..86d8c7c42 100644 --- a/docs/token-studio-sunset.md +++ b/docs/token-studio-sunset.md @@ -2,7 +2,7 @@ -**Status:** Draft roadmap, Phase 0 in progress. +**Status:** Draft roadmap. Phase 0 and Phase 1 complete; Phase 2 (verify Figma export parity) next. ## Why @@ -24,37 +24,38 @@ that native path. ### Phase 0 — now (unblocked) -- Ship the [token change request issue form](../.github/ISSUE_TEMPLATE/token-change-request.yml) +* Ship the [token change request issue form](../.github/ISSUE_TEMPLATE/token-change-request.yml) as the designer-facing intake, replacing "open a Token Studio PR" for one-off requests. -- Announce the new intake in `#spectrum-tokens`; Token Studio still accepted during +* Announce the new intake in `#spectrum-tokens`; Token Studio still accepted during transition. -### Phase 1 — foundation-corpus write target (gating) +### Phase 1 — foundation-corpus write target (gating) — done -The shipped CLI/TUI/MCP authoring write path currently targets product-layer files, not -the foundation corpus (`packages/design-data/tokens/*.tokens.json`). Redirecting it is -**Phase B** in `authoring-workflow.md` §Scheduled promotion, and is **not yet shipped**. -Nothing below can complete until this lands. Track as its own epic; see RFC +The CLI/TUI/MCP authoring write path now targets the foundation corpus +(`packages/design-data/tokens/*.tokens.json`) directly, rather than product-layer files. This +redirect was **Phase B** in `authoring-workflow.md` §Scheduled promotion and has **shipped** +(epic `spectrum-design-data-122`, +closed). Phases below are unblocked; see RFC [#625](https://github.com/adobe/spectrum-design-data/discussions/625). ### Phase 2 — verify Figma export parity -- Confirm `design-data figma export` reads the cascade token format +* Confirm `design-data figma export` reads the cascade token format (`packages/design-data/tokens/`) end to end. The CLI help text calls its input a "legacy token source directory" — that naming is overloaded; verify `build_export_payload`'s expected input shape in `sdk/core/src/figma/mapping.rs` before relying on it. -- Confirm round-trip to legacy output (`design-data:legacy-output`, +* Confirm round-trip to legacy output (`design-data:legacy-output`, `design-data:roundtrip-verify`) so `@adobe/spectrum-tokens` consumers see no regression. ### Phase 3 — decommission the inbound sync Once the native path is authoritative and verified, retire: -- `tools/token-changeset-generator/` -- `.github/workflows/enhance-sync-pr.yml` -- `.github/actions/extract-source-pr-info` -- the `enhance-sync-pr` skill +* `tools/token-changeset-generator/` +* `.github/workflows/enhance-sync-pr.yml` +* `.github/actions/extract-source-pr-info` +* the `enhance-sync-pr` skill Coordinate with the external `spectrum-tokens-studio-data` repo owners (`mrcjhicks`) — sync PRs originate there, so this is a cross-repo change, not a delete-and-done in this repo. diff --git a/packages/design-data-spec/spec/agent-surface.md b/packages/design-data-spec/spec/agent-surface.md index 3cdbf0b3e..32561531c 100644 --- a/packages/design-data-spec/spec/agent-surface.md +++ b/packages/design-data-spec/spec/agent-surface.md @@ -25,19 +25,19 @@ The surface targets three consumer shapes: **NORMATIVE:** A conforming implementation MUST expose the following operations. Transport-specific naming (CLI subcommand vs MCP tool name vs skill action) MAY differ; the semantics MUST NOT. -| Operation | Reads | Returns | Backed by | -| -------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | -| `resolve_token` | property + mode set context | winning token (literal or resolved alias) with file/UUID/specificity | `cascade::resolve` | -| `query_tokens` | filter expression (see [Query](query.md)) | matching token list | `query::filter` | -| `validate_usage` | candidate token document or fragment | `ValidationReport` (Layer 1 + Layer 2 diagnostics) | `validate::validate_*` | -| `describe_component` | component identifier | component contract (anatomy, options, states, tokenBindings); see [#832](https://github.com/adobe/spectrum-design-data/discussions/832) and [Phase 6.7](#describe_component-return-shape) | (Phase 6 contract) | -| `suggest_token` | natural-language intent + optional property hint | ranked candidate tokens with rationale (RECOMMENDED, not NORMATIVE in v1) | registry + query | -| `get_guidance` | token UUID, component identifier, or anatomy reference | attached document blocks (Phase 9 / RFC-D); falls back to empty list pre-RFC-D | document blocks | -| `diff_datasets` | two dataset roots | `DiffReport` per [Diff](diff.md) | `diff::semantic_diff` | -| `write_token` | token object + optional rationale string | updated product-layer token file + `product-context.json` (RECOMMENDED, not NORMATIVE in v1) | `write::write_token` — shipped: `design-data write-token` (CLI) / `authoring_session_commit` (MCP) | -| `write_component` | component object + optional rationale string | updated dataset-root component file (RECOMMENDED, not NORMATIVE in v1; scheduled to become MUST — see [Scheduled promotion](authoring-workflow.md#scheduled-promotion)) | `write::write_component` — Phase B scheduled; not yet implemented | - -**NORMATIVE:** `validate_usage`, `resolve_token`, `query_tokens`, `diff_datasets`, and `describe_component` MUST be implemented in a conforming agent surface. `suggest_token`, `get_guidance`, `write_token`, and `write_component` are RECOMMENDED. `write_token` and `write_component` are scheduled to become MUST when the Phase B foundation-corpus write target ships — see [Authoring workflow — Scheduled promotion](authoring-workflow.md#scheduled-promotion). +| Operation | Reads | Returns | Backed by | +| -------------------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | +| `resolve_token` | property + mode set context | winning token (literal or resolved alias) with file/UUID/specificity | `cascade::resolve` | +| `query_tokens` | filter expression (see [Query](query.md)) | matching token list | `query::filter` | +| `validate_usage` | candidate token document or fragment | `ValidationReport` (Layer 1 + Layer 2 diagnostics) | `validate::validate_*` | +| `describe_component` | component identifier | component contract (anatomy, options, states, tokenBindings); see [#832](https://github.com/adobe/spectrum-design-data/discussions/832) and [Phase 6.7](#describe_component-return-shape) | (Phase 6 contract) | +| `suggest_token` | natural-language intent + optional property hint | ranked candidate tokens with rationale (RECOMMENDED, not NORMATIVE in v1) | registry + query | +| `get_guidance` | token UUID, component identifier, or anatomy reference | attached document blocks (Phase 9 / RFC-D); falls back to empty list pre-RFC-D | document blocks | +| `diff_datasets` | two dataset roots | `DiffReport` per [Diff](diff.md) | `diff::semantic_diff` | +| `write_token` | token object + optional rationale string | updated dataset-root token file + `product-context.json` (**NORMATIVE** — MUST, promoted with the Phase B foundation-corpus write target; see [Scheduled promotion](authoring-workflow.md#scheduled-promotion)) | `write::write_token` — shipped: `design-data write-token` (CLI) / `authoring_session_commit` (MCP) | +| `write_component` | component object + optional rationale string | updated dataset-root component file (RECOMMENDED, not NORMATIVE in v1; scheduled to become MUST — see [Scheduled promotion](authoring-workflow.md#scheduled-promotion)) | `write::write_component` — Phase B scheduled; not yet implemented | + +**NORMATIVE:** `validate_usage`, `resolve_token`, `query_tokens`, `diff_datasets`, `describe_component`, and `write_token` MUST be implemented in a conforming agent surface. `suggest_token`, `get_guidance`, and `write_component` are RECOMMENDED. `write_token` was promoted to MUST now that the Phase B foundation-corpus write target has shipped; `write_component` remains RECOMMENDED pending component authoring support — see [Authoring workflow — Scheduled promotion](authoring-workflow.md#scheduled-promotion). **RECOMMENDED:** When `write_token` or `write_component` is invoked, the implementation SHOULD capture a `rationale` argument from the agent session context and record it in both the token's inline `rationale` field and the product context document's `overrides[].rationale` or `extensions.tokens[].rationale`. See [Product context — Agent capture behavior](product-context.md#agent-capture-behavior). diff --git a/packages/design-data-spec/spec/authoring-workflow.md b/packages/design-data-spec/spec/authoring-workflow.md index c6293ecab..76db13b3c 100644 --- a/packages/design-data-spec/spec/authoring-workflow.md +++ b/packages/design-data-spec/spec/authoring-workflow.md @@ -35,20 +35,20 @@ Per [Evolution — Legacy format contract](evolution.md#legacy-format-contract), The following tools constitute the normative authoring surface: -| Tool | Form | Status | Scope | -| -------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------- | -| `design-data` CLI | `design-data write-token` subcommand | Shipped — product-layer token creation | Foundation corpus authoring: see [Gap — Phase B](#scheduled-promotion) | -| `design-data-tui` | interactive token naming + creation wizard | Shipped (RFC [#973](https://github.com/adobe/spectrum-design-data/discussions/973)) | Foundation corpus authoring: see [Gap — Phase B](#scheduled-promotion) | -| MCP authoring session | `start_authoring_session` / `authoring_session_commit` tools | Shipped (RFC [#973](https://github.com/adobe/spectrum-design-data/discussions/973)) | Foundation corpus authoring: see [Gap — Phase B](#scheduled-promotion) | -| Design Data management app | future browser-based tool | Not yet shipped | Full CRUD across all categories | +| Tool | Form | Status | Scope | +| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | +| `design-data` CLI | `design-data write-token` + cascade mutation/mode-set subcommands (edit/deprecate/rename/alias-rewire/remove, add-mode/rename-mode/remove-mode/create-mode-set/remove-mode-set) | Shipped — cascade foundation-corpus token + mode-set authoring (Phase B, epic [`spectrum-design-data-122`](https://github.com/adobe/spectrum-design-data/issues/122)) | Component/field/registry authoring not yet shipped — see [Per-category authoring contracts](#per-category-authoring-contracts) | +| `design-data-tui` | interactive token naming + creation wizard | Shipped (RFC [#973](https://github.com/adobe/spectrum-design-data/discussions/973)); writes cascade `*.tokens.json` directly (Phase B) | Component/field/registry authoring not yet shipped | +| MCP authoring session | `start_authoring_session` / `authoring_session_commit` tools, plus `edit_token`/`deprecate_token`/`rename_token`/`rewire_alias`/`remove_token`/mode-set tools | Shipped (RFC [#973](https://github.com/adobe/spectrum-design-data/discussions/973)); writes cascade `*.tokens.json` directly (Phase B) | Component/field/registry authoring not yet shipped | +| Design Data management app | future browser-based tool | Not yet shipped | Full CRUD across all categories | **RECOMMENDED:** Authors SHOULD use the TUI or MCP authoring session rather than editing cascade JSON files directly. Tooling enforces UUID uniqueness, name-object field decomposition, and referential integrity that is difficult to maintain manually. ### Scheduled promotion {#scheduled-promotion} -The shipped CLI/TUI/MCP write path currently targets product-layer files (`foundation.json`, `platform.json`, `product.json`) — the distributed design system model introduced for product teams. Redirecting those tools to write to the foundation Spectrum corpus (`packages/design-data/tokens/*.tokens.json`) is Phase B work. +The CLI/TUI/MCP write path now targets the foundation Spectrum corpus (`packages/design-data/tokens/*.tokens.json`, via `design_data_core::write::cascade_target_filename`) rather than the legacy product-layer files (`foundation.json`, `platform.json`, `product.json`). This redirect was **Phase B** work and has shipped (epic [`spectrum-design-data-122`](https://github.com/adobe/spectrum-design-data/issues/122), closed). -**NORMATIVE:** Once the Phase B authoring engine ships, all authoring tools described above MUST write to the dataset root, not to legacy layer files. The `write_token` and `write_component` operations in [Agent-readable surface](agent-surface.md) are currently RECOMMENDED; they are **scheduled to become required** (MUST) when the Phase B foundation-corpus write target ships. The exact promotion version is tracked in RFC [#625](https://github.com/adobe/spectrum-design-data/discussions/625). This mirrors the SPEC-017 escalation precedent in [Token format](token-format.md#string-name-escape-hatch--spec-017-severity-schedule). +**NORMATIVE:** All authoring tools described above MUST write to the dataset root, not to legacy layer files. The `write_token` operation in [Agent-readable surface](agent-surface.md) is now **required** (MUST) for the foundation-corpus write target; `write_component` remains RECOMMENDED pending component authoring support (not yet shipped — see [Per-category authoring contracts](#per-category-authoring-contracts)). The promotion is tracked in RFC [#625](https://github.com/adobe/spectrum-design-data/discussions/625). This mirrors the SPEC-017 escalation precedent in [Token format](token-format.md#string-name-escape-hatch--spec-017-severity-schedule). ## Lifecycle operations @@ -78,14 +78,14 @@ The following table defines the **target token-authoring contract**: the complet The following per-category contracts specify what the authoring surface authors in each registered directory and which validation rules gate the output. Detailed authoring workflows per category are specified in separate subsections of this document as Phase A work progresses. -| Category | Directory | Authoring status | Validation gate | -| ---------- | ------------- | -------------------------------------------------------------------------------- | ------------------------------------------ | -| Tokens | `tokens/` | Shipped (create only; edit/lifecycle operations are Phase B) | SPEC-001–017, SPEC-041, SPEC-042, SPEC-043 | -| Components | `components/` | Not yet shipped (`write_component` deferred — [Agent surface](agent-surface.md)) | SPEC-018–040 | -| Fields | `fields/` | Not yet shipped | SPEC-042, SPEC-043 | -| Mode sets | `mode-sets/` | Not yet shipped | SPEC-005, SPEC-008, SPEC-041 | -| Guidelines | `guidelines/` | Not yet shipped | SPEC-045, SPEC-046 | -| Registry | `registry/` | Not yet shipped (vocabulary is hand-maintained) | SPEC-033, SPEC-034, SPEC-035 | +| Category | Directory | Authoring status | Validation gate | +| ---------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | +| Tokens | `tokens/` | Shipped — create, edit, deprecate, rename, alias-rewire, remove (Phase B, epic [`spectrum-design-data-122`](https://github.com/adobe/spectrum-design-data/issues/122)) | SPEC-001–017, SPEC-041, SPEC-042, SPEC-043 | +| Components | `components/` | Not yet shipped (`write_component` deferred — [Agent surface](agent-surface.md)) | SPEC-018–040 | +| Fields | `fields/` | Not yet shipped | SPEC-042, SPEC-043 | +| Mode sets | `mode-sets/` | Shipped — add/rename/remove-mode, create/remove-mode-set (Phase B, epic [`spectrum-design-data-122`](https://github.com/adobe/spectrum-design-data/issues/122)) | SPEC-005, SPEC-008, SPEC-041 | +| Guidelines | `guidelines/` | Not yet shipped as a manual authoring surface; generated via extended transformer (Phase 10, beads `ek4`) | SPEC-045, SPEC-046 | +| Registry | `registry/` | Not yet shipped (vocabulary is hand-maintained) | SPEC-033, SPEC-034, SPEC-035 | ### Token authoring contract @@ -106,9 +106,9 @@ Tokens are authored in `tokens/**/*.tokens.json`. Files may be nested arbitraril **Validation gate:** SPEC-001–017 (name, value, lifecycle, tech-debt), SPEC-041 (mode-set conformance), SPEC-042 (field-scope), SPEC-043 (domain-required-fields). -**Edit and lifecycle operations (Phase B):** Edit, deprecate, rename, alias-rewire, mode-set +**Edit and lifecycle operations (Phase B, shipped):** Edit, deprecate, rename, alias-rewire, mode-set management, and remove are specified in [Lifecycle operations](#lifecycle-operations) and are -implemented in Phase B. +implemented (epic [`spectrum-design-data-122`](https://github.com/adobe/spectrum-design-data/issues/122), closed). *** @@ -134,8 +134,8 @@ be named with the component's `name` field value (e.g. `button.json` for `name: cross-references), SPEC-034 (category registry sync), SPEC-035 (anatomy-term registry sync), SPEC-038–040 (lifecycle, display name, schema). -**Authoring status:** Not yet shipped — `write_component` is Phase B scheduled (see -[Scheduled promotion](#scheduled-promotion)). +**Authoring status:** Not yet shipped — `write_component` was out of scope for Phase B (tokens and +mode-sets only; see [Scheduled promotion](#scheduled-promotion)) and remains unscheduled. ***