skills for everythingworkleap-chromatic-best-practices
Audit and update repositories to follow Workleap's Chromatic best practices for snapshot cost control and CI optimization. Use this skill when: (1) Auditing a repository for Chromatic best practices compliance (2) Implementing Chromatic cost optimizations in a project (3) Fixing TurboSnap-disabling patterns in code (4) Setting up chromatic.config.json with the untraced option (5) Updating CI workflows for conditional Chromatic execution (6) Refactoring barrel file imports in Storybook preview files (7) Reviewing PRs for Chromatic cost impact (8) Setting up Chromatic in a new Turborepo project (9) Checking for local Chromatic usage that should be removed
SKILL.md
| Name | workleap-chromatic-best-practices |
| Description | Audit and update repositories to follow Workleap's Chromatic best practices for snapshot cost control and CI optimization. Use this skill when: (1) Auditing a repository for Chromatic best practices compliance (2) Implementing Chromatic cost optimizations in a project (3) Fixing TurboSnap-disabling patterns in code (4) Setting up chromatic.config.json with the untraced option (5) Updating CI workflows for conditional Chromatic execution (6) Refactoring barrel file imports in Storybook preview files (7) Reviewing PRs for Chromatic cost impact (8) Setting up Chromatic in a new Turborepo project (9) Checking for local Chromatic usage that should be removed |
name: workleap-chromatic-best-practices description: | Workleap's Chromatic best practices for snapshot cost control and CI optimization. Use when auditing, setting up, or fixing Chromatic configurations — including TurboSnap-disabling patterns, CI workflows, chromatic.config.json, and monorepo setups. Also activate when reviewing PRs that touch Storybook or Chromatic-related files. metadata: version: 1.3
Workleap Chromatic Best Practices
Guide for auditing and updating repositories to follow Workleap's Chromatic best practices.
Audit Workflow
When asked to audit or update a repository for Chromatic best practices, follow these steps in order.
Step 1: Locate Chromatic Configuration
Search for existing Chromatic setup:
chromatic.config.json
.storybook/preview.ts[x]
.github/workflows/*chromatic*.yml or *storybook*.yml
package.json (scripts section)
If no Chromatic configuration exists, ask the user if they want to set it up.
Step 2: Audit and Fix Each Practice
Run through all 10 checks below. For detailed code examples, detection patterns, and fix actions for each check, consult references/audit-checks.md.
| # | Check | What to look for |
|---|---|---|
| 2.1 | untraced config (optional) | chromatic.config.json — ask user about cost vs. regression trade-off |
| 2.2 | Preview barrel imports | .storybook/preview.ts[x] — barrel/index imports that disable TurboSnap |
| 2.3 | Local Chromatic scripts | package.json scripts — remove local chromatic commands |
| 2.4 | CI label-based triggering | GitHub Actions — require run chromatic label on PRs |
| 2.5 | CI required flags | chromaui/action — onlyChanged, exitOnceUploaded, autoAcceptChanges |
| 2.6 | CI git checkout depth | actions/checkout — fetch-depth: 0 + Chromatic env vars |
| 2.7 | Browser configuration | CLI flags — Chrome only, remove multi-browser flags |
| 2.8 | Renovate/Changesets exclusion | Branch ruleset — exclude bot branches from required checks |
| 2.9 | Large preview dependencies | Preview imports — flag files with >20 exports or >500 lines |
| 2.10 | Workflow optimizations | CI concurrency settings + label auto-removal step |
Step 3: Generate Audit Report
After completing all checks, generate a findings table with pass/fail status and actions taken. See references/audit-checks.md for the report template.
Critical Rules
- Stick to documented Chromatic options — inventing undocumented flags can silently break TurboSnap or produce invalid builds
- Run Chromatic from CI only — local runs trigger the entire visual test suite and waste snapshots against the monthly budget
- Preserve TurboSnap — TurboSnap is the primary cost-saving mechanism; every recommendation should maintain its effectiveness
- Cost awareness — every snapshot counts toward the monthly budget, so always consider the snapshot cost impact of changes
Reference Guide
For detailed documentation beyond the workflow above, consult:
references/audit-checks.md— Full check procedures with code examples, detection patterns, fix actions, and the audit report templatereferences/background.md— TurboSnap preservation rules, snapshot cost multipliers, CI trigger strategy, monorepo-specific checks