ARFC-1016: Design Component Identity and Design-Implementation Traceability

Status

Draft

Date: 2026-08-22

Version: 0.3

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-22, so that this design carries the same Draft → Last Call → Published review lifecycle as a platform-facing proposal. Precedent: ARFC-1008.

---

Abstract

This ARFC proposes a Design Component Identity capability: a shared naming, namespace, and documentation discipline covering every reusable interface element defined in the platform’s design source and carried through into its shipped implementation. It defines what a component identity is, how its namespace is scoped, what a variant attribute must satisfy to be named as such, when a component identity requires recorded documentation, what a traceability relationship between a design-source element and its shipped counterpart must guarantee, and who holds authority to establish or change any of the above. It does not mandate a specific tool, retroactively remediate any existing design library, or commit to a procurement decision.

Table of Contents

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

Introduction

The platform’s interface is authored twice: once as a design artifact, and once as a shipped implementation. The two are produced on different cadences, often by different people, and today share no required correspondence. An interface element — a card, a badge, a status indicator — can be defined in the design source and, independently, defined again in the shipped implementation, with nothing recording whether the two represent the same concept, a deliberate variation, or an accidental duplicate.

This ARFC establishes a naming and traceability discipline that gives every reusable interface element one identity, shared between its design source and its implementation, together with the rules that keep that identity meaningful over time. It is a capability for the people who design and build the platform’s interface, not for its instructors, students, or API integrators — but per the scope note above, it is being carried through the full ARFC review lifecycle by explicit operator direction.

Motivation

Current State

• Interface elements are authored independently in the design source and in the shipped implementation, with no required naming correspondence between the two.
• A design element’s points of variation — the specific ways one instance differs from another instance of “the same” element — are frequently left unnamed or carry a default, non-descriptive label, so a reviewer cannot tell what a variation represents without inspecting the design source directly.
• A component’s name is not required to be accompanied by any statement of its intent. When a name is not self-explanatory — an abbreviation, a domain-specific shorthand, or a term borrowed from a different context — nothing records what it means for a future reader.
• Two interface elements that are visually and functionally equivalent can be authored independently, under different names, by different areas of ownership, with no mechanism to detect the duplication after the fact — nor to confirm, when two similarly-named elements turn out to serve different purposes, that the difference was intentional rather than accidental.

Missing Capabilities

• There is no stable identity that both the design source and the shipped implementation can refer to for “the same” interface element.
• There is no rule for how narrowly or broadly an identity’s namespace should be scoped, so each area of ownership invents its own convention independently, and namespace depth is not tied to any consistent principle.
• There is no requirement that a named variation of a component correspond to a real, evidenced difference in behavior or content, rather than an arbitrary or default label.
• There is no recorded authority for who may establish a new component identity versus reuse an existing one, so preventing duplication is not anyone’s responsibility.

Design Goals

1. Give every reusable interface element one stable identity, shared between its design source and its shipped implementation.
2. Scope an identity’s namespace to its actual ownership and reuse boundary, rather than a fixed depth applied uniformly regardless of need.
3. Require that a named variation of a component correspond to a verifiable difference, and that its name describe that difference rather than serve as a placeholder.
4. Require a recorded statement of intent for any component identity whose meaning is not self-evident from its name alone.
5. Establish a traceability relationship such that a shipped implementation can be resolved back to its design-source identity, or be explicitly marked as not design-sourced.
6. Establish who holds authority to define, rename, or reorganize a component identity, and how a conflicting claim between two areas of ownership is resolved.

Specification

Core Principles

• One identity, two representations. A component identity is a single, stable name that both the design source and the shipped implementation resolve to. The two representations may differ in medium, but must agree on identity.
• Namespace follows ownership, not a fixed schema. An identity’s namespace reflects who actually owns and reuses the component. A shared, cross-cutting concept is scoped broadly; a concept specific to one area of the platform is scoped to that area. Namespace depth grows only when there is enough real density beneath it to justify organizing further — never by default.
• A name must be legible on its own. The final, most specific segment of a component identity must identify what kind of element it is without requiring its surrounding namespace for context.
• Containment implies inheritance. A component that exists only in relation to a containing component takes that container’s identity as its own prefix, rather than being assigned an independent identity in the same namespace.
• A variation must be a real variation. A named point of variation on a component (its “variant attribute”) must correspond to a distinction that actually exists in the component’s behavior or content. A distinction that cannot be evidenced is not given a name — the component instead carries open, undifferentiated content.
• Silence is not documentation. A component identity whose meaning is not self-evident requires a recorded statement of what it represents. Absence of documentation is never treated as evidence that none was needed.

Primary Objects

Component Identity — The stable name of one reusable interface element, shared by its design source and its shipped implementation. An identity is structured as an ordered sequence of segments: a namespace (see below) followed by a final segment identifying the element’s kind. Two elements that are functionally and visually equivalent share one identity; two elements that are deliberately distinct are given distinct identities, never disambiguated by context alone.

Namespace — The portion of a component identity that scopes its ownership and reuse boundary. A namespace may be shared across the entire platform (for concepts with no single owning area), or scoped to a particular area of the platform’s interface. A namespace gains additional levels only when an existing level has accumulated enough distinct components to make further organization useful; it is never pre-emptively subdivided.

Variant Attribute — A named dimension along which instances that share one component identity differ from one another. A variant attribute’s name must describe the actual distinction it represents (for example, a component’s stage in a review process, or its visual size), rather than being an unnamed placeholder. A component whose apparent “variations” are really open-ended, arbitrary content is not given a variant attribute for that content — the content is left undifferentiated.

Component Documentation — A recorded statement of what a component identity represents, required whenever the identity’s name would not be self-evident to a reader unfamiliar with the specific feature it belongs to (for example, a domain-specific abbreviation). Documentation states what the component is for, and — where relevant — whether the content it displays is fixed or stands in for content that varies at runtime.

Traceability Relationship — The declared relationship between a component identity’s design-source representation and its shipped implementation. A component may exist in the design source only, in the implementation only (explicitly, not incidentally), or in both — in which case the relationship is Traced: both representations exist and agree on identity.

A representation counts toward this relationship only once it is in its authoritative, generally-visible form. A design-source or implementation representation that exists only in a personal or otherwise unpublished draft state does not yet satisfy Design-Sourced or Implemented — those states require the representation to be the one other people and other tooling would actually see.

For example, a course-summary card and the individual insight entries it contains are declared as related component identities, with the summary card containing instances of the entry. When both a design-source and an implementation representation exist for each and agree on identity, the pair is Traced. If a summary card is later found in the shipped implementation with no declared design-source counterpart, it is flagged Divergent until the naming authority confirms whether it is a legitimate implementation-only component or an undeclared duplicate of something already defined.

Naming Authority — The role responsible for establishing, renaming, or reorganizing a component identity or namespace, and for resolving a conflict when two areas of ownership independently claim to represent the same concept.

Lifecycle

A component identity’s traceability progresses through the following states:

stateDiagram-v2
    [*] --> Proposed
    Proposed --> Adopted: naming authority accepts
    Proposed --> Refused: collides with an existing identity for a different concept
    Refused --> Proposed: resubmitted under a disambiguated name
    Adopted --> DesignSourced: representation added to the design source
    Adopted --> Implemented: representation added to the shipped implementation
    DesignSourced --> Traced: implementation representation added
    Implemented --> Traced: design-source representation added
    Traced --> Divergent: an independently-authored duplicate identity is discovered
    Divergent --> Reconciled: naming authority merges the duplicate, or confirms both are deliberately distinct
    Reconciled --> Traced
    Traced --> Deprecated: superseded by a successor identity
    Deprecated --> [*]

The relationships among the primary objects are:

flowchart TB
    NA[Naming Authority] -->|adopts and resolves conflicts for| CI[Component Identity]
    CI -->|scoped by| NS[Namespace]
    CI -->|may declare| VA[Variant Attribute]
    CI -->|requires, when not self-evident| DOC[Component Documentation]
    CI -->|tracked through| TR[Traceability Relationship]
    TR -->|resolves to| DS[Design-Source Representation]
    TR -->|resolves to| IMPL[Implementation Representation]

Authorization

A designated naming authority may adopt, rename, or reorganize a component identity or namespace. A contributor proposing a new identity is expected to check whether an existing adopted identity already represents the same concept before proposing a new one; when uncertain, the proposal goes to the naming authority for a reuse-or-new determination rather than being decided unilaterally by the proposer. When two independently-authored elements are found to represent the same concept under different identities, the naming authority — not either original author acting alone — decides whether they are merged under one identity or confirmed as deliberately distinct, and records the reasoning either way.

An area of ownership may propose an identity within its own namespace without escalation. It may not unilaterally establish an identity in the shared namespace, and may not use its own namespace for a concept that is genuinely cross-cutting — such a proposal is redirected to the shared namespace and the naming authority.

Configuration

Each area of ownership may configure the internal subdivision of its own namespace — how finely to organize the components it owns — subject to the namespace principle above (subdivide only where density justifies it). No area of ownership may configure a namespace boundary outside its own scope, and the shared namespace’s structure is configured only by the naming authority.

Error and Edge-Case Behavior

• A proposed identity that collides with an existing adopted identity for a different concept is refused; the proposer is directed to choose a disambiguating name rather than the collision being silently accepted.
• A variant attribute proposed without an evidenced, real distinction behind it is not adopted as a variant attribute; the proposer either demonstrates the distinction or withdraws it in favor of undifferentiated content.
• A component identity requiring documentation under the rule above is not adopted until that documentation is recorded — this is a condition of adoption, not a follow-up task that can be deferred indefinitely.
• A component discovered to exist in the shipped implementation with no design-source representation, and no explicit record that it is intentionally implementation-only, is treated as Divergent and routed to the naming authority the same as a duplicate would be.

Version 1 Scope

Included:

• The definition of a component identity, its namespace-scoping principle, the requirement that its final segment be self-descriptive, and the containment-inheritance rule.
• The variant-attribute naming discipline, requiring an evidenced, real distinction behind any named variation.
• The component-documentation requirement for identities whose meaning is not self-evident.
• The traceability relationship and its lifecycle, including divergence detection and resolution.
• The naming authority role, its scope of authority, and the conflict resolution process.

Deliberately excluded:

• Mandating any specific design tool, or any specific mechanism for automatically enforcing or verifying traceability.
• Retroactively remediating any existing design library or implementation to conform to this capability; V1 applies to identities proposed going forward.
• Any procurement, licensing, or plan-tier decision that a future enforcement mechanism might require.
• Continuous or automated verification tooling — a future ARFC or implementation effort may propose this once the underlying discipline is in place.
• Internal code organization, file layout, or design-tool folder structure — these are implementation decisions made in service of the identities this ARFC defines, not part of the capability itself.

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. The naming authority is a governance role over design and implementation artifacts, not a runtime system privilege, and its actions are not exposed through the platform API.

Because component identities and their documentation may be visible broadly across design and engineering tooling, documentation should be scoped to what is appropriate for that visibility — it is not a substitute for, and should not be used to record, security-sensitive rationale or unreleased feature details beyond what the design tool’s own audience is expected to see.

Backward Compatibility

Adoption of this capability does not retroactively rename, reorganize, or otherwise change any existing design-source or implementation element. Version 1 applies to component identities proposed from adoption forward; a decision to remediate the existing design library against this discipline is a separate, explicitly excluded, follow-on effort.

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-1008: GitHub Issue Lifecycle Automation — precedent for filing a 100%-internal engineering-process design as a formal ARFC under explicit operator direction.
• ARFC-1001: URN-Based Asset Identifiers — related precedent for a platform-wide identifier scheme; a structural analog for the component-identity scheme this ARFC proposes.
• codermerlin.academy-frontend#2025 — pilot rollout tracking issue, holding the concrete Figma naming examples and illustrative implementation code that this ARFC’s altitude gate excludes from the document itself.

Author

ĀYŌDÈ Development Team Codermerlin Academy Architecture