[DRAFT RFC] Token Authoring Workflow and Process

[GarthDB]

⚠️ DRAFT STATUS: This RFC is in draft form and open for feedback. This focuses on establishing the authoring workflow, tooling, and publishing process.

---

RFC: Token Authoring Workflow and Process

Status: Draft in Progress
Author: [To be assigned]
DACI: [To be assigned]
Related: DNA-[ticket], Onsite Day 2 "Data Authoring" discussion

---

Executive Summary

This RFC proposes a comprehensive workflow and tooling strategy for authoring, reviewing, publishing, and managing design tokens across the foundation and platform layers of the Spectrum design data system.

Problem: Current token authoring is ad-hoc, lacks validation, has no review process, and creates coordination overhead between design and engineering.

Solution: Establish a formal authoring workflow with validation, branching, reviews, and automated publishing that supports both foundational and platform team needs.

---

Background & Context

Origin

• August 2025 Onsite - Day 2: "Data Authoring" discussion
• August 2025 Onsite - Day 2: "Spec Files" discussion
• Nate's Prototype: Authoring tool demo on Day 1

Current Pain Points

From Onsite Discussions:

1. No Validation: Errors discovered late in process
2. No Review Process: Changes go directly to production
3. Fragmented Tools: Token Studio, Figma, JSON files, spreadsheets
4. No Versioning: Can't track changes or rollback
5. Manual Publishing: Error-prone, time-consuming
6. Coordination Overhead: Design and engineering out of sync

From Day 2 Onsite Notes:

• Lack of stable naming contracts disrupts engineering
• No notification system for design asset changes
• Metadata loss during implementation
• Cultural barriers (sprint-based dev bypasses process)

---

Proposal

Authoring Workflow Overview

1. AUTHOR → Create/edit tokens with validation (Web tool / Figma limited)
2. VALIDATE → Schema, taxonomy, type, and relationship checks
3. BRANCH/PR → Create GitHub PR with change documentation
4. REVIEW → Peer review (Foundation team / Platform validation)
5. APPROVE → Steward approval (Foundation: RFC | Platform: Lead)
6. PUBLISH → Automated build, generate formats, Figma sync
7. NOTIFY → Release notes, Slack, email digest, changelog

Authoring Tools

Web-Based Token Editor (Primary Tool)

From: Nate's prototype demonstration (Day 1 onsite)

Features:

• Load tokens from GitHub repositories
• Taxonomy-enforced naming
• Schema validation in real-time
• Multi-dimensional token editing (modes)
• Platform/theme override management
• Figma variable integration
• AI-assisted token creation and analysis

Figma (Secondary, View-Only for Most)

Limited Role:

• View foundation tokens as variables
• Consume tokens in designs
• NOT primary authoring environment (prevents validation issues)
• Design-led teams can prototype, but must migrate to web tool for publication

Rationale: Figma can't enforce schema, taxonomy, or validation rules

---

Branching & Review Process

Foundation Tokens

Process:

1. Create feature branch from main
2. Author changes in web tool or JSON
3. Schema validation runs automatically
4. Create PR with change description, rationale, affected platforms
5. Review by Foundation team (2 approvals) + Platform team (advisory)
6. Approval by foundation steward
7. Merge to main
8. Automated publish

Platform Tokens

Process:

1. Create branch in platform-specific repo/folder
2. Author changes with validation
3. Create PR with description
4. Review by platform team (1-2 approvals)
5. Platform steward approval
6. Merge and publish

---

Validation Rules

Enforced at Authoring Time:

• Schema compliance: All required fields present, correct types
• Taxonomy compliance: Token names follow approved conventions
• Relationship validation: References to other tokens are valid
• Tier compliance: Platform overrides have foundation parent
• Duplicate detection: No naming conflicts
• Mode coverage: All required modes have values

---

Publishing Pipeline

Automated Build Process:

GitHub PR Merge
  ↓
Trigger CI/CD
  ↓
Generate Outputs (CSS, Design Tokens JSON, iOS Swift, Android XML, Figma)
  ↓
Run Tests (Schema, output, visual regression)
  ↓
Publish to NPM/Registry
  ↓
Update Documentation Site
  ↓
Notify Stakeholders
  ↓
Create Release Notes

Publishing Cadence:

• Foundation: Monthly major, weekly minor, daily patches (bugfixes)
• Platform: Platform-determined
• Urgent fixes: On-demand with approval

---

Notification & Communication

Automatic Notifications:

• Slack: Post to #spectrum-implementations on publish
• Email Digest: Weekly summary to subscribers
• GitHub Release: Automated release notes with changelog
• Wiki Update: Documentation auto-updated

Addresses Onsite Feedback: Automated notification system for design asset updates (Day 2 follow-up task)

---

User Personas & Workflows

Persona 1: Foundation Designer

Goal: Create new semantic color token for dark mode

Workflow:

1. Open web token editor
2. Browse existing semantic colors
3. Click "Add Token"
4. Name: background-subtle-hover (validated against taxonomy)
5. Define values for light/dark modes
6. Save → creates branch and PR automatically
7. Add description and rationale in PR
8. Request review from foundation team
9. Iterate based on feedback
10. Approved → merges and publishes

Persona 2: Platform Engineer (iOS)

Goal: Override button background for iOS tint system

Workflow:

1. Open web token editor
2. Switch to iOS platform view
3. Find button-background-default
4. Click "Override for iOS"
5. Set new value: {accent-color-tinted}
6. Add reason: "iOS applies tint for native feel"
7. Validation checks foundation relationship
8. Save → PR in iOS section
9. iOS team review and approve
10. Publishes to iOS outputs only

---

Open Questions

1. Tooling: Build custom web tool or adapt existing (e.g., Knapsack, Token Studio)?
2. Figma Integration: One-way or two-way sync? How to handle conflicts?
3. AI Features: What AI assistance is most valuable? (from Nate's prototype)
4. Multi-user: Do we need real-time collaborative editing?
5. Offline: Should tool work offline or require network?
6. Permissions: Who can author foundation vs platform tokens?

---

References

• August 2025 Onsite: Day 2 "Data Authoring" session
• August 2025 Onsite: Day 2 "Spec Files Discussion"
• Nate's "Authoring Complex Design Data" presentation (Day 1)
• Day 2 Follow-up Tasks: Authoring workflow definition
• Day 3 Follow-up Tasks: Token authoring tool validation
• Platform team feedback from governance meetings

---

Full RFC: View complete RFC with all technical architecture details

[GarthDB]

🔗 Related Work: Token Schema Structure RFC

A new RFC has been published that provides validation infrastructure for token authoring workflows:

RFC: Token Schema Structure and Validation System (PR #644)

How It Relates

The schema validation system can be integrated into the authoring workflow:

• ✅ CI/CD validation - Automated checks in PRs
• ✅ Naming convention enforcement - 12 enum schemas with 800+ controlled values
• ✅ Token pattern validation - Ensures tokens follow established patterns
• ✅ Reference validation - Checks that aliased tokens exist

Workflow Integration Points

# In CI/CD pipeline
$ pnpm validate-tokens
✓ All 2,338 tokens validated
✗ Error: "button-height-350" - index not in allowed sizes
✗ Error: "unknown-component" - component not in enum

This validation tooling can be part of the authoring workflow gates defined in your RFC.

Current State

• Production-ready validator with AJV
• 82% validation coverage (improving)
• Detailed error reports for debugging