Replies: 1 comment
-
|
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. |
Beta Was this translation helpful? Give feedback.
0 replies
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
-
poc_automation.feedback_rfc.mov
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
The pipeline requires 3 commands in VS Code terminal:
node pipeline/parser.js input/component_raw.txtnode pipeline/shaper.js output/component_raw_parsed.jsonnode pipeline/apply-to-schema.js output/component_raw_shaped.json01. 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)
️️⚠️ (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:
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)
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.
Input: component_raw.text
Divider: missing static white and static black propOutput: component_raw_parsed.json
What the output of the script answers:
Human pain point aimed to solve:
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
Output: component_raw_shaped.json
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
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:
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.
Why steps 4-5 use manual human oversight in this pipeline proposal:
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
Beta Was this translation helpful? Give feedback.
All reactions