Skip to content

Spectrum CSS Engineering Workflow

Jump to bottom
[ Cassondra ] edited this page May 26, 2023 · 4 revisions

Incoming Tasks

We bring in and prioritize work from the following sources:

  • Prototype tasks that are automatically generated by the design team via Jiratron
  • Parsing each SDL release for potential CSS work
  • Attending regular component review with web framework teams
  • Attending design's regular workshop meetings
  • Responding to customer requests via Slack and GitHub issues

For all monitoring above:

  • Commit at least one engineer in advance
  • Rotate each sprint
  • Ping other engineers as needed to join

Points 9-13 are asynchronous.

Workflow

  1. File issues for upcoming work
    • Jiratron automatically files prototype issues
    • Issues are filed in Jira by engineering in meetings, as work arises
    • Issues filed by community and migrated into Jira for prioritization
  2. Formalize prototype or scope plan, if needed
    • Filter issues from Jiratron, meetings, community
    • Each sprint has a formal backlog grooming and sprint planning exercise
  3. Prototype major changes
    • Codepen
    • Leverage existing packages
  4. Vet prototypes with Design
    • Design workshop is ideal
    • QOTD Slack can supplement needed
  5. Vet with implementations
    • Web frameworks have a per-sprint engineering sync for this
  6. Issue for tokens
    • Start conversation with CSS token needs
    • File issues for token work and reference in CSS work issue
  7. GitHub pull request
    • Expected final CSS/Markup/Metadata
    • Request PR review from engineering peeps via Slack
    • Add or update visual regression tests (VRT) as needed
  8. File Jira issue for design review
    • Use Jira issues to notify Design and track work
    • Discuss in Design Workshop
    • Use generated link from visual regression testing
  9. Visual regression test
    • Automated
    • Generates link for review
    • Must be created or updated for work to be complete
  10. Request accessibility audit
    • Use GitHub pull request code review
  11. Update pull request with tokens
    • When tokens are released with updates
    • Lint embedded tokens
  12. Final engineering review
    • Not full browser QA check
    • Sanity check
    • Naming check
    • Check visual regression testing
  13. Release
    • Use Semver, consult peeps if which type of bump is unclear
    • NPM packages
  14. Update/release docs
    • Automatically triggered with GitHub tag
  15. Notify consumers
    • Slack channels

Pull requests

Pull requests open against the main branch that meet the following requirements will receive automatic updates whenever the target branch is updated.

  • Not in a draft state
  • Is one of the first 50 open PRs, sorted by most recently updated
  • Does not include the blocked or wip labels

Component development

Any structural changes or visual updates must be approved by the Spectrum Design team. If you are not sure who to contact, please open an issue and we can help it get added to the appropriate backlogs for discussion and consideration. If you want to pick up an existing issue and contribute changes, please don't hesitate to comment in the issue with questions as well as leave @pfulton or @castastrophe a message letting us know that you're picking up this work.

The project is currently undergoing a migration from our old token library (@spectrum-css/vars) to a new one (@spectrum-css/tokens). To this end, any new tokens leveraged in the repository should try to be sourced from @spectrum-css/tokens first. If an appropriate token does not exist there yet, you can fallback to either hardcoding or leveraging a @spectrum-css/vars token. Please reach out to us with questions. You can find more about developing for the migration project here.

Any pull request that influences the visual output for components (i.e., CSS, storybook, markup changes, or PostCSS changes) must pass visual regression testing (VRT) via Chromatic. Reach out to the project maintainers to receive access to the team's Chromatic project. This access will grant you a project token which must be added to the .env file in your tools/preview/ directory if you are to run Chromatic locally. A token is not necessary if you are letting CI manage your VRT runs (recommended).

Tooling and non-component development

If your PR does not involve updates to how components are rendered or what the compiled output looks like, it does not need to run VRT. Please add the skip_vrt label. This will pass the workflow without running VRT, allowing the PR to merge. All PRs must "pass" VRT in order to be merged, either through an approved skip, actually passing, or getting diffs approved by assigned stakeholders.

Clone this wiki locally