[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, RFC #714 — Spectrum Design Data Specification, RFC #715 — Distributed Design Data Architecture, RFC #646 — Token Schema / cascade, RFC coordination outline

---

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 — including distributed platform-owned repositories as described in RFC #715.

---

Distributed authoring model

The umbrella spec (RFC #714) positions a Design Data Management App that writes changes as pull requests to the correct repository (foundation or platform) on behalf of an authenticated user, so every edit stays versioned and reviewable.

• Foundation changes still land in spectrum-design-data (or successor foundation repo) with foundation review gates.
• Platform changes land in each platform’s design-data repo, validated against the pinned foundation version and platform manifest (RFC #715).
• Cascade-aware authoring (RFC #646): the tool should surface dimension context (e.g. color scheme, scale), specificity (non-default structured properties), coverage for required mode combinations, and explicit combination requirements when multiple dimensions are overridden — with fast validation suitable for watch/on-save workflows.

---

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

Design Data Management App / Web editor (primary tool)

From: Nate's prototype (Day 1 onsite), evolving into the management app described in RFC #714 / RFC #715.

Features:

• Load resolved or source data from GitHub (foundation + platform repos)
• Taxonomy- and schema-enforced naming (RFC #646)
• Real-time validation (including cascade / dimension coverage)
• Author dimension-specific tokens without nested sets (target model)
• Manage platform manifest fields (include/exclude queries, type-safe overrides, extensions)
• Create PRs (user-authenticated) instead of writing directly to protected branches
• Figma variable integration (from resolved sets)
• 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 (distributed)

Process:

1. Create branch in the platform-owned design data repository (not only a folder in foundation)
2. Ensure foundationVersion / manifest aligns with intended release
3. Author changes with validation against pinned foundation + manifest rules
4. Open PR in the platform repo (optionally opened by the management app)
5. Review by platform team (1–2 approvals)
6. Platform steward approval
7. Merge and publish platform artifacts

---

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
• Cascade rules: Specificity and explicit multi-dimension combinations per RFC #646
• Manifest rules: Type-safe overrides, valid foundation version (RFC #715)

---

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 the iOS design-data repo (or iOS section if still transitional)
9. iOS team review and approve
10. Publishes to iOS outputs only

---

Open Questions

0. Distributed model (partially answered): RFC #714 / RFC #715 — PR-based authoring to platform repos + management app; refine UX details below.
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

• RFC #714 — Spectrum Design Data Specification
• RFC #715 — Distributed Design Data Architecture
• RFC #646 — Token Schema Structure and Validation
• RFC coordination outline
• 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

[GarthDB]

Related RFC: The [DRAFT RFC] Spectrum Design Data Specification (#714) describes a Design Data Management App that authors changes by opening pull requests to platform repos (as the authenticated user). That app is the concrete realization of the authoring tool envisioned in this discussion, extended to a distributed model where each platform (SWC, RSP, iOS, Android) owns its own design data repo.

We plan to update this Token Authoring Workflow discussion to align with the distributed model once the spec RFC is stabilized.

See: #714

[GarthDB]

Update (March 2026): Added distributed authoring model (PRs to platform repos, management app), cascade-aware validation bullets, and spec cross-links.

[GarthDB]

Update (April 2026): Phase 4 status.

Authoring workflow is tracked under Phase 4 on the project board. Two Phase 4 items are complete (legacy JSON output via PR #794, Figma Variables PoC via PR #795). Three items remain in Todo: authoring workflow definitions, wireframe generation from workflow definitions, and authoring app architecture design document.

The taxonomy naming framework (#806) and the platform manifest formatting extensions (PR #807) are now available as building blocks for the authoring workflow — particularly the semantic/dimension field validation and platform-specific formatting configuration.