[DRAFT RFC] Component Schema Feedback Automation Pipeline

[AmunMRa]

poc_automation.feedback_rfc.mov

⚠️ DRAFT STATUS: This RFC is in draft form, it is not ready for feedback at this time.

RFC: Component Schema Feedback Automation Pipeline

Status: Draft in Progress
Author: Amun Ra
Related: Epic SDS-15983

---

Executive Summary

This RFC proposes the maintenance process for how designer feedback transitions from existing Paper documentation into component-schema JSON, establishing the foundation for scalable, consistent schema maintenance across Spectrum components.

Problem

The component-schema repo has no structured workflow for turning designer feedback into validated, consistent schema updates. Feedback currently lives as raw text in Paper with no defined method for interpretation, no shared rules for accuracy, and no mechanism for transforming it into actionable JSON changes. As contributions grow across teams and components, the lack of a standardized intake, validation, and update process creates fragmentation, inconsistent schema quality, and heavy manual oversight that does not scale. The system needs a predictable, source-agnostic pipeline that can reliably convert human feedback into governed, review-ready schema changes.

Solution

Establish a structured, automation-supported pipeline that transforms designer feedback into validated, review-ready schema updates, without requiring designers to manually edit JSON or have technical knowledge of how JSON works.

The pipeline is intentionally separated into distinct scripts so that errors surface earlier, are easier to diagnose, and can be addressed at the right stage without contaminating downstream steps. This modularity also enables different contributors to own different parts of the workflow without touching the full system. Together, the pipeline allows a visible and predictable process that design and implementation partners can rely on to communicate, track, and maintain schema changes.

Context

Designers on Spectrum have not typically contributed directly to the component-schema repo, often relying on slack messages to engineering partners to communicate desired changes. This is due to the fact that designers have not been equipped with the training or expectation to use Github as a tool. With the rising demand for making machine-readable data and working with AI in Spectrum (key 2026 org pillar: make it AI-able), it is becoming increasingly difficult to close the gap between expected skillset and existing workflows. This proposed pipeline aims to close that gap using deterministic logic scripts that are lightweight. This proposal aims to establish faster contribution as well as a visible and predictable process that design and implementation partners can rely on to communicate, track, and maintain schema changes.

---

Proposal

Pipeline
├── 00. Designer Feedback
│   └── Raw sentences (source agnostic), variable clarity (raw text)
│
├── 01. Property Map ⚠️ built, but design has not approved props
│   └── Maps existing props across all components
│   └── Serves as verification layer, allowing humans to verify feedback 
│
├── 02. Parser ✅ built
│   ├── Reads raw feedback
│   ├── Applies property map (inference + renaming)
│   ├── Detects component, action, and property intent
│   └── Outputs structured logic for each feedback line
│
├── 03. Shaper ✅ built
│   ├── Normalizes parser output
│   ├── Prepares JSON to be applied in apply-to-schema script
│   └── Produces clean, schema-ready JSON entries
│
├── 04. Apply-to-Schema ✅ built 
│   ├── Creates branch and names it, routes update to correct component schema file
│   ├── Inserts actual schema block (e.g., new property)
│   └── Produces review-ready JSON update in the repo
│
└── 05. Git Workflow (Human)
    ├── Create branch
    ├── Review diff locally
    ├── Commit change
    ├── Publish branch
    └── Open PR for engineering review

The pipeline requires 3 commands in VS Code terminal:

• node pipeline/parser.js input/component_raw.txt
• node pipeline/shaper.js output/component_raw_parsed.json
• node pipeline/apply-to-schema.js output/component_raw_shaped.json

---

01. Property Map: JSON file that maps all existing properties to existing components

property-map.json

The property map maps all existing properties to all existing components within the component-schema repo. It looks for the following:

Same type? (eg: string)
Same description?
Same defaults? (eg: null)
Same enum values? (eg: null)

• This serves as the foundation for the parser to infer the correct property to identify. Only the parser reads from the property map, allowing a clear, auditable point of divergence to be identified.

️️ ⚠️ (need help/suggestions for this) The property map was generated from all properties that currently exist in the repo, but were not changed or examined for approval.

Below is an excerpt from the existing property map from POC:

"actionLabel": {
    "componentsUsedIn": [
      "alert-banner",
      "drop-zone",
      "in-line-alert",
      "tag-group",
      "toast"
    ],

for verification of missing props, the reverse-map.json serves as a reference, though the pipeline does not read from the reverse map, the reverse map is an aid for humans to verify if properties are missing.

---

02. Parser.json: Script that interprets designer feedback from raw text (00) and infers property names from the Property Map (01)

• Feedback written in natural language (currently in Paper) is processed by a deterministic parser that identifies component names, action types (e.g., missing, deprecated), and inferred property names using the property-map (00)

Because the parser operates purely on raw text, its strength is source-agnostic input. It doesn’t care whether the text comes from Paper, Slack, Figma notes, or any future tool. As long as designers can express feedback in words, the pipeline can interpret, structure, and route it.

• This removes ambiguity and reduces reliance on memory or interpretation.

Input: component_raw.text

Divider: missing static white and static black prop

Output: component_raw_parsed.json

// Example output from PARSER stage:
[
  {
    "raw": "Divider: missing static white and static black prop",
    "component": "Divider",
    "property": "staticColor",
    "action": "missing"
  }
]

What the output of the script answers:

• What was the exact feedback (raw)?
• Which component does the individual line of feedback refer to?
• Which prop is the individual line of feedback pointing to?

Human pain point aimed to solve:

• Determining which component, prop, and format for writing in JSON is time-consuming and requires frequent context-switching between design terminology and component-schema terminology.

Machine pain point aimed to solve:

• Each feedback line contains typos, inconsistent sentence structure, contains questions, and varies in descriptiveness across 60+ components.

• The parser transforms raw human feedback into structured logic, creating the foundation for automating edits down the pipeline.

---

03. Shaper.json: Script that turns parser output into consistent schema-ready format

The parser output is transformed into clean, structured JSON, stripping out human text and standardizing the data model. This creates a predictable contract between design intent and downstream schema updates.

Input: component_raw_parsed.json

// Example input for SHAPER stage (from PARSER):
[
  {
    "raw": "Divider: missing static white and static black prop",
    "component": "Divider",
    "property": "staticColor",
    "action": "missing"
  }
]

Output: component_raw_shaped.json

// Example output for SHAPER stage:
[
  {
    "component": "Divider",
    "action": "missing",
    "proposedProperty": "staticColor"
  }
]

Human pain point aimed to solve:

• Designers and reviewers struggle to interpret mixed raw text, component names, and technical signals when feedback is represented inconsistently.

• Humans need a clean, standardized representation that reflects intent without the noise of the original sentence.

Machine pain point aimed to solve:

• Downstream scripts cannot operate on human-language structures, partial matches, or inconsistent keys.

• The shaper converts parsed signals into a predictable, normalized JSON contract the rest of the pipeline can read, ensuring every update follows the same structure and meaning before it is applied to the schema.

---

04. Apply-to-schema.json : Safely creates branch and applies review-ready schema updates into correct component

• A branch is automatically created and named after the change the user made

• The structured data is applied to the component in retained structure

• This step initiates the rest of the Git workflow, which will remain manual: publishing the branch, creating a PR, submitting the PR for engineering review.

Input: component_raw_shaped.json

// Example input for APPLY TO SCHEMA stage (from SHAPER):
[
  {
    "component": "Divider",
    "action": "missing",
    "proposedProperty": "staticColor"
  }
]

Output: Within local copy of the repo, the proper JSON format is inserted at the bottom of the correct component, formatted correctly using conventions that match the repo. Screenshot below is the real example from POC in VS Code.

Human pain point aimed to solve:

• Manually inserting changes into the correct component-schema file is error-prone and requires specialized knowledge of schema structure, folder organization, and property formatting.
• This step removes the need for designers or reviewers to navigate JSON files directly, and produces clean, review-ready updates.

Machine pain point aimed to solve:

• The schema repo cannot consume raw or semi-structured feedback. It requires strict JSON structures, canonical property placement, and consistency across 60+ components.

• The apply-to-schema step writes structured updates into the correct JSON file, ensuring schema changes are programmatically safe, correctly formatted, and ready for Git-based review.

---

The following steps are manual to allow control of actually making PRs, publishing changes, and making PRs public to teammates.

• [5. Manual] Review the diff locally (no extra files shown in ‘Changes’).
• [5. Manual] Commit the change with a valid conventional message (e.g. chore(divider): add auto-generated pendingProps (pipeline POC)).
• [5. Manual] Publish the branch to origin.
• [5. Manual] When ready, open a PR from that branch into main and request review.
• [5. Manual] Removal of props remain manual, this automation pipeline does not perform deprecations

Why steps 4-5 use manual human oversight in this pipeline proposal:

• Maintain governance: manual review of the diff between main and branch ensures every update is reviewed, titled correctly, and scoped properly
• Keep control centralized: manual open of PR from branch to prevent a flood of automated branches/PRs while the system matures.

---

APPENDIX A. Property Maps

🔗 Property Map
Lists every property and shows which components use them. Good for finding inconsistencies in naming and use.
property-map.json

🔗 Reverse Property Map
Lists every component and what props it uses. Nested properties have a dot next to them (eg. items.content). Good for detecting if a prop is missing.
reverse-map.json

[AmunMRa]

I generated a property map (see appendix above) that lists every prop in the system and shows which components use it, along with how each component defines that prop. It’s useful for spotting inconsistencies or differences in naming across components.

I also generated a reverse map (see appendix above) that shows each component and all of the props it uses in one place, which makes it easy to understand a component’s full options at a glance.