ARFC-1017: Design Source Synchronization

Status

Draft

Date: 2026-08-28

Version: 0.1

Scope note: This ARFC deliberately documents a 100% internal design/engineering-process capability — it has no effect on the ĀYŌDÈ platform, the Codermerlin Academy API, or any developer/end-user-visible behavior. It is filed here, rather than as a plain docs/silicon-based-how/ note or a GitHub issue body (the normally-prescribed vehicles for internal tooling per this repository’s ARFC scope gate), per explicit operator direction on 2026-08-28, so that this design carries the same Draft → Last Call → Published review lifecycle as a platform-facing proposal. Precedent: ARFC-1008, ARFC-1016.

---

Abstract

This ARFC proposes a Design Source Synchronization capability: a repeatable, automated process that compares a design source’s current authoritative state against a previously recorded code-side copy, for both component structure and the design tokens components reference, and produces an updated record together with a report of what changed. It extends ARFC-1016’s identity and traceability model with one new primary object — the Design Token — and with the automated mechanism that ARFC-1016 deliberately deferred. It does not mandate a specific tool, credential mechanism, file format, or run schedule.

Table of Contents

• Introduction
• Motivation
  • Current State
  • Missing Capabilities
  • Design Goals
• Specification
  • Core Principles
  • Primary Objects
  • Relationship to ARFC-1016
  • Lifecycle
  • Authorization
  • Error and Edge-Case Behavior
  • Version 1 Scope
• Security Considerations
• Backward Compatibility
• References
• Author

Introduction

ARFC-1016 establishes that every reusable interface element has one identity, shared between its design source and its shipped implementation, and defines the states that relationship can be in. It deliberately stops short of defining any automated mechanism for keeping that relationship current, or for detecting when it has drifted — those were named as explicitly excluded from its V1 scope.

This ARFC picks up exactly there. It defines what it means to run a synchronization between a design source and a code-side record, what such a run produces, and how it detects that a previously-recorded value or structure is no longer current. It also introduces a primary object ARFC-1016 does not cover: the Design Token — a named, reusable value (a color, a measurement, a typographic style) that components reference, as distinct from the components themselves.

Motivation

Current State

• A component’s identity and structure can, per ARFC-1016, be traced between its design source and its implementation — but the values a component references (its colors, spacing, radii, typography) have no equivalent identity or traceability model at all.
• When a design source’s authoritative value changes, nothing detects that a previously-recorded code-side value no longer matches it. The correspondence, where it exists, is established once and never rechecked.
• Every mechanism observed for keeping a design-to-code correspondence current has depended on a person remembering to perform a manual step at the right time. When that step is skipped, the correspondence silently stops being true, and nothing signals that it happened.
• Design values that should be shared by many components are independently approximated by each one instead, because there is no authoritative, reusable record of what the value actually is.

Missing Capabilities

• There is no identity for a reusable design value distinct from the components that use it, so two components can reference what is meant to be “the same” value without any way to confirm they actually do.
• There is no repeatable process that compares the design source’s current state to a recorded copy and reports what has changed.
• There is no notion of a record becoming stale — a synchronized copy is either trusted indefinitely or re-verified only by chance.

Design Goals

1. Give every reusable design value one identity, on the same terms ARFC-1016 gives a component identity.
2. Define a repeatable act of comparing a design source’s current state to a recorded copy, for both component structure and design token values.
3. Detect, as a result of that act, when a recorded copy no longer matches the design source’s current state.
4. Route any naming conflict or undocumented identity a synchronization run discovers to the same Naming Authority ARFC-1016 already defines, rather than establishing a second, competing governance path.

Specification

Core Principles

• A value is an identity too. A design token is not an attribute of one component; it is its own reusable, identifiable thing, named and documented on the same terms as a component identity.
• Synchronization is a repeatable act, not a one-time event. A single successful comparison does not make a record permanently trustworthy — the capability is the ability to repeat the comparison, not the fact that it once succeeded.
• Staleness is discovered, not assumed away. A synchronized record is presumed potentially stale until a run confirms otherwise; silence is not evidence of currency, the same principle ARFC-1016 applies to documentation.
• This capability reuses governance, it does not duplicate it. A synchronization run does not adopt, rename, or resolve conflicts itself — it surfaces them to the Naming Authority ARFC-1016 already establishes.

Primary Objects

Design Token — A named, reusable value that one or more component identities reference: a color, a measurement, a typographic style, or similar. A Design Token has its own identity, independent of any single component that uses it, and requires documentation under the same rule ARFC-1016 applies to a component identity whose meaning is not self-evident.

Synchronization Run — A discrete act of comparing the design source’s current authoritative state against the last-recorded copy, for both Component Identities (per ARFC-1016) and Design Tokens, and producing an updated record together with a report of what changed since the previous run.

Synchronized Representation — The record a run produces or refreshes for a given identity. It is distinct from an ARFC-1016 Implemented representation in one respect: it is produced mechanically by the synchronization process, not authored by a person, and states only that a reference exists — never that a real, hand-built implementation does.

Staleness — The state of a Synchronized Representation when a run determines the design source has changed since that representation was last produced. Staleness is the automated counterpart to ARFC-1016’s Divergent traceability state, extended to cover Design Tokens (which that lifecycle does not), and discovered by repetition rather than by incidental observation.

Relationship to ARFC-1016

This ARFC does not redefine Component Identity, Namespace, Variant Attribute, or the Naming Authority — it reuses all of them without modification. A Synchronization Run that discovers a naming collision, an undocumented identity, or a component present in the design source with no recorded counterpart follows ARFC-1016’s existing rules for those cases exactly; this ARFC contributes only the repeatable mechanism that surfaces them, and the Design Token object that ARFC-1016’s model does not include.

Lifecycle

stateDiagram-v2
    [*] --> Current: Synchronization Run confirms match
    Current --> Stale: design source changes since last run
    Stale --> Current: next run refreshes the Synchronized Representation
    Stale --> Conflict: run finds a naming collision or undocumented identity
    Conflict --> Current: Naming Authority resolves per ARFC-1016

Authorization

A Synchronization Run does not have authority to adopt a new identity, rename an existing one, or decide that two identities are the same concept — those decisions remain the Naming Authority’s alone, per ARFC-1016. A run that encounters any such case records it and leaves the affected identity in Conflict until the Naming Authority resolves it; the run is not blocked from proceeding with everything else it can synchronize in the meantime.

Error and Edge-Case Behavior

• A design token discovered with no recorded identity is treated the same way ARFC-1016 treats an undeclared component: flagged for the Naming Authority, not silently assigned one by the synchronization process.
• A run that cannot reach the design source, or reaches it in a partially readable state, reports exactly what it could and could not synchronize — it does not mark unreachable identities as stale, since staleness is a finding about the design source’s content, not about connectivity.
• A Synchronized Representation is never treated as evidence that a real Implemented representation (per ARFC-1016) exists; the two remain distinct claims.

Version 1 Scope

Included:

• Design Token as a primary object, with its own identity and documentation requirement.
• The Synchronization Run concept and the change report it produces.
• Staleness detection for both Component Identities and Design Tokens.
• Routing of conflicts and undocumented identities to the existing ARFC-1016 Naming Authority.

Deliberately excluded:

• The specific tool, language, or hosting mechanism that performs a run.
• Credential or secret-handling mechanics.
• File formats or code organization for a Synchronized Representation.
• Run cadence or scheduling.
• Any change to ARFC-1016’s Component Identity, Namespace, Variant Attribute, or Naming Authority definitions.

Security Considerations

This capability governs an internal design/engineering artifact and introduces no change to the ĀYŌDÈ platform’s authentication, authorization, or end-user-facing privilege model. A Synchronization Run reads design source content and produces internal records; it does not expose, modify, or gate access to any platform resource.

Because a Synchronization Run reads the full current state of a design source, any credential it uses should be scoped no more broadly than the content it needs to compare — a run’s own authorization is an implementation concern (see V1 exclusions), but the principle of least privilege applies to whatever mechanism is chosen.

Backward Compatibility

Adoption of this capability does not change any existing ARFC-1016 Component Identity, Namespace, or Traceability Relationship state. It adds a new object (Design Token) and a new automated process; nothing in ARFC-1016 is redefined, and no existing recorded identity is invalidated by this ARFC’s adoption.

This capability has no effect on any existing developer- or end-user-visible platform behavior, API endpoint, or schema — it governs the internal design-to-implementation process only.

References

• ARFC-1016: Design Component Identity and Design-Implementation Traceability — the identity, namespace, and traceability model this ARFC extends; Component Identity, Namespace, Variant Attribute, and Naming Authority are reused here without modification.
• ARFC-1008: GitHub Issue Lifecycle Automation — precedent for filing a 100%-internal engineering-process design as a formal ARFC under explicit operator direction.

Author

ĀYŌDÈ Development Team Codermerlin Academy Architecture