Developer Handoff
Developer Handoff is the Pro workflow for compiling a palette into theme variants, roles, component tokens, Figma Variables, framework exports, and production previews.
Free view
- Shows a Pro Workflow summary.
- Highlights 3 theme modes and 3 token layers.
- Lists Pro features such as theme matrix, semantic tokens, component tokens, AA contrast repair, Component Preview Lab, Figma handoff, and advanced exports.
- Includes an Unlock Pro button.
Pro workflow
- Choose a theme variant: Light, Dark, or High Contrast.
- Review role token count, AA check coverage, and best pair metric.
- If semantic pairs fail AA, tap Auto-Fix AA.
- Use Figma Handoff when the design team needs variables and modes.
- Choose a role preset for the target system.
- Inspect the Theme Matrix across all variants.
- Use the Component Preview Lab to see the palette in real UI structures.
- Compare against another palette in Palette Diff.
- Review primitive, semantic, and component token lists.
- Open Export and share the final format.
Figma Handoff
The Figma Handoff block shows one color collection, three modes, and the number of variables ChromaForge will share. Tap Share Variables to export Figma Variables JSON.
| Layer | What it contains | Figma mapping |
|---|---|---|
| Primitive | Direct palette stops such as palette-50 and palette-500. | color/primitive/... variables with the same value in every mode. |
| Semantic | Purpose-based roles such as background, foreground, surface, primary, warning, and danger. | color/semantic/... variables with Light, Dark, and High Contrast mode values. |
| Component | UI-specific roles such as button primary background, input focus border, link foreground, and focus-ring outline. | color/component/... variables expressed as aliases to semantic roles, with resolved fallback colors included. |
Share CSS shortcut
The Developer Handoff header includes Share CSS, which shares Semantic CSS for the current palette.
Tokens & Theme Variants
Primitive tokens
Primitive tokens are direct palette stops. ChromaForge names them like palette-50, palette-100, palette-200, and so on when the stop count fits the standard 50-950 scale. If a palette has more stops, it uses numeric names such as 100, 200, 300.
Semantic tokens
| Role | Token | Use |
|---|---|---|
| Background | --color-background | Base page or app canvas. |
| Foreground | --color-foreground | Primary text and icons. |
| Surface | --color-surface | Cards, panels, grouped areas. |
| Surface Raised | --color-surface-raised | Elevated surfaces, popovers, dialogs. |
| Border | --color-border | Borders, dividers, subdued copy, grids. |
| Primary | --color-primary | Primary actions and brand tint. |
| Secondary | --color-secondary | Secondary actions and supporting accents. |
| Accent | --color-accent | Links, focus rings, expressive accents. |
| Success | --color-success | Positive status and success markers. |
| Warning | --color-warning | Caution status and warnings. |
| Danger | --color-danger | Errors, destructive actions, failure status. |
Component tokens
Component tokens bind semantic roles to UI use cases, such as button-primary-background, input-focus-border, alert-warning-background, link-default-foreground, and focus-ring-default-outline. Each row shows the token name, semantic reference, and hex value.
Theme variants
| Variant | How ChromaForge maps it | Color scheme |
|---|---|---|
| Light | Uses the lightest stop as background, selects the highest-contrast foreground, and builds surfaces slightly below the background. | light |
| Dark | Uses the darkest stop as background, selects the highest-contrast foreground, and builds progressively raised surfaces. | dark |
| High Contrast | Starts from an even darker base, chooses strong foreground contrast, and lifts surfaces for clearer boundaries. | dark |
Role Presets
Role presets translate ChromaForge semantic roles into the naming conventions expected by common UI systems.
| Preset | Aliases generated |
|---|---|
| ChromaForge | color.background, color.foreground, color.surfaceRaised, and all native semantic roles. |
| shadcn/ui | background, foreground, card, popover, primary, secondary, muted, accent, destructive, border, input, and ring with foreground variants. |
| Material 3 | primary, on-primary, primary-container, secondary, tertiary, surface, surface-container-high, on-surface, outline, error, and on-error. |
| Apple UI | systemBackground, secondarySystemBackground, tertiarySystemBackground, label, secondaryLabel, tintColor, separator, systemFill, systemGreen, systemYellow, and systemRed. |
| Data Viz | chart-background, chart-grid, chart-label, and categorical chart-series-N colors. |
Component Preview Lab
The Component Preview Lab renders semantic tokens in a compact product UI so you can evaluate real use cases, not only swatches.
Previewed patterns
- Account card with headline and supporting copy.
- Primary and secondary buttons.
- Email input with focus ring.
- Success, warning, and danger badges.
- Sidebar navigation with selected and unselected rows.
- Progress bars and chart bars.
- Invite member modal/dialog pattern.
- Status list with queued, running, and failed markers.
- Code surface showing a theme token path.
How to review a component preview
- Choose a theme variant in Developer Handoff.
- Scan text readability first: headings, labels, helper copy, and code text.
- Check action hierarchy: primary should be obvious; secondary should not disappear.
- Check focus and status colors: ring, success, warning, and danger need enough separation from the background.
- If the preview fails, use Auto-Fix AA, change stops, or generate a different harmony.
Palette Diff
Palette Diff compares the current palette against another palette in your library. It measures both primitive stop changes and semantic token changes using perceptual distance.
Compare palettes
- Open Developer Handoff.
- In Palette Diff, choose another palette from the Compare picker.
- Review Changed, Largest, and From metrics.
- Inspect the highest semantic changes and stop changes.
- Use the before/after swatches to decide whether the difference is intentional.
What the distance means
Distance is calculated in OKLab-style perceptual space. Larger values usually mean a more visible shift in lightness or color. A low stop distance can still produce a meaningful semantic shift if the changed color becomes background, foreground, primary, or danger.
Export Formats
The Export panel shows the selected format as selectable monospaced text. If the format is available, tap Share to send it to Files, Mail, Messages, another app, or your development workflow. Free includes 5 basic exports; Pro unlocks unlimited exports and advanced handoff formats.
Free exports
Free exports include JSON, Mandelbrot Metal, and raw CSS Variables. The Free export counter advances when you share one of these formats. When all 5 free exports are used, open Pricing to unlock unlimited exports.
| Format | What it contains |
|---|---|
| JSON | Full ChromaForge palette model with name, subtitle, kind, color space, LUT resolution, notes, recipe, dates, favorite state, stops, positions, colors, and locks. |
| Mandelbrot Metal | Palette JSON with schema version, name, color space, normalized stop positions, RGB components, and optional notes. |
| CSS Variables | Raw :root variables named from the palette slug and stop index. |
Pro exports
| Format | Use it when |
|---|---|
| Modern CSS | You want hex fallbacks, OKLCH values, Display-P3 strings, @supports, light-dark(), and color-mix() helpers. |
| Semantic CSS | You need light, dark, high-contrast, prefers-color-scheme, semantic variables, and component variables. |
| Tailwind | You need a classic Tailwind config extension with palette and app colors. |
| Tailwind v4 | You need CSS-first @theme and @theme inline output. |
| shadcn/ui | You need OKLCH variables for :root, .dark, and shadcn @theme inline aliases. |
| SwiftUI | You need an extension Color with primitive and semantic static colors. |
| Swift Assets | You need a plan for creating .colorset entries in Assets.xcassets for light, dark, and high contrast. |
| Sass | You need Sass variables for primitive stops and semantic roles. |
| Android XML | You need <color> resources for Android light and dark roles. |
| Compose | You need Jetpack Compose Material 3 lightColorScheme and darkColorScheme. |
| Flutter | You need Dart ColorScheme definitions for light and dark themes. |
| React Native | You need a typed theme object with light, dark, and high-contrast colors. |
| DTCG 2025.10 | You need structured design-token JSON with $schema, $type, $value, and semantic groups. |
| Tokens Studio | You need JSON shaped for Tokens Studio-style workflows. |
| Style Dictionary | You need JSON for a Style Dictionary token build pipeline. |
| Figma Variables | You need a Figma-oriented JSON handoff with one color collection, Light/Dark/High Contrast modes, primitive colors, semantic tokens, component aliases, code syntax, and resolved color values. |
| CSV | You need spreadsheet-friendly rows with index, position, hex, red, green, blue, and locked state. |
Export a palette
- Open the Export disclosure panel.
- Choose a format from the picker.
- If the format is Pro-only and you are on Free, tap Unlock Export or choose a free format.
- If the Free export counter has reached 5/5, tap Upgrade for Unlimited Exports.
- Review the generated text.
- Tap Share to send the export where you need it.
CLI / CI Audit
The repository includes a starter command-line audit script at Tools/chromaforge-cli.swift. It extracts hex colors from CSS, JSON, or text, calculates every foreground/background pair, reports contrast coverage, and exits non-zero when not every pair passes AA normal-text contrast.
On Mac, open Tools > CLI Utility inside ChromaForge to review common commands, or choose Tools > Copy CLI Audit Command to copy a starter audit command to the pasteboard.
Run the audit
swift Tools/chromaforge-cli.swift audit path/to/tokens-or-css-file.cssWhat the CLI reports
- File name being audited.
- Number of unique colors found.
- Total pair count.
- AA normal coverage at 4.5:1.
- AA large / non-text coverage at 3:1.
- AAA coverage at 7:1.
- Weakest foreground/background pair.
- Strongest foreground/background pair.
Use it as a CI gate
- Export CSS or tokens from ChromaForge.
- Commit the file to your design-system or app repository.
- Add the Swift CLI command to your CI workflow.
- Fail the build when the script exits non-zero.
- Return to ChromaForge, repair or adjust colors, export again, and rerun the audit.