Troubleshooting
I cannot create another palette
- Free allows 5 custom/imported palettes. Delete or reuse a palette, or upgrade to Pro for unlimited palettes.
Website import says the URL is invalid
- Use a real website host. ChromaForge supports http and https only.
- If you type example.com, ChromaForge tries https://example.com.
Website import found no usable colors
- The page may hide colors behind scripts, remote styles unavailable to the importer, images, canvas, or unsupported syntax.
- Try the public homepage, a CSS file URL, or a different page with static HTML/CSS.
Figma Variables export is locked
- Figma Variables is a Pro export because it depends on the advanced theme, semantic token, and component-token pipeline.
- Open Pricing and purchase or restore a Pro plan to unlock it.
A Pro export is locked
- Choose JSON, Mandelbrot Metal, or raw CSS variables on Free.
- Open Pricing and purchase or restore a Pro plan to unlock advanced developer exports.
I cannot export another free palette
- Free includes 5 basic exports. The counter advances when you share JSON, Mandelbrot Metal, or raw CSS variables.
- Upgrade to Pro for unlimited exports, or continue editing and validating palettes before using another export.
A purchase option says unavailable
- ChromaForge loads paid plans from App Store Connect. If a product is unavailable, the App Store product metadata may be missing, not approved, removed from sale, or still propagating in sandbox.
- Check that the product IDs in App Store Connect exactly match the IDs shown in the pricing section of this guide.
The gradient looks banded
- Turn off Exact LUT preview for smooth gradient review.
- Switch LUT metadata to 1024 for high-resolution handoff.
- Turn on Dithering preview to judge whether texture helps subtle ramps.
- Add intermediate stops or use Perceptual Blend.
I cannot find how to close a sheet on Mac
- Use the visible Close button in the sheet.
- You can also press Escape to dismiss Mac sheets.
Accessibility checks fail after generation
- Use Auto-Fix AA in Developer Handoff for semantic pairs.
- Lock background and foreground colors, then regenerate remaining stops.
- Increase lightness separation between text roles and surface roles.
- Check color-vision simulation after repair.
I changed a palette by accident
- Use Undo Last Palette Change in the detail header or editable panels to restore the previous palette snapshot.
- If you edited a built-in palette and want the original version, use Restore Factory Palette from Render Preview, the selected-palette actions menu, row context menu, or trailing swipe action.
- If you want to experiment without risk, duplicate the palette first and edit the custom copy.
Display-P3 colors look different in another app
- The destination may not support wide-gamut color or may clamp to sRGB.
- Use sRGB when the output must match broadly across older displays and tools.
- Use Modern CSS output when you want OKLCH and P3 strings plus fallbacks.
FAQ
Is ChromaForge only a palette generator?
No. It generates and edits palettes, but its main purpose is compiling colors into accessible themes, semantic tokens, component tokens, framework roles, exports, and audit output.
What should I do first with a new brand color?
Create a new palette, set the brand color as a stop, lock it, choose a harmony, and generate unlocked stops. Then inspect Context Preview, Accessibility, System Audit, and Developer Handoff before exporting.
How do I organize a busy palette library?
Use the sidebar filter for All, Built-In, Imported, or Custom, then use the Sort menu for Favorites, Newest, Oldest, Name, Most Stops, Fewest Stops, Type, Color Space, or LUT Size. Search still matches names, subtitles, notes, and generation recipes.
What is the safest way to branch an idea?
Duplicate the palette before making experimental edits. Duplicates become custom palettes, get a unique copy name, and count toward the Free plan custom/imported palette limit.
Should I use sRGB or Display-P3?
Use sRGB for maximum compatibility. Use Display-P3 for wide-gamut Apple and modern display workflows, especially when saturated colors are part of the brand. Modern CSS can export both P3 and fallback values.
What does Auto-Fix AA change?
It adjusts failing semantic foreground roles toward a 4.5:1 WCAG AA target against their backgrounds. It uses OKLCH-aware foreground adjustment, reduces chroma as needed, locks background and foreground roles in the repaired palette, and records a note.
Can Auto-Fix AA make every possible color pair accessible?
No. It targets semantic theme checks, not every arbitrary stop-to-stop combination. Use the Accessibility panel and System Audit to review broader risks.
What is the difference between primitive, semantic, and component tokens?
Primitive tokens are raw palette stops. Semantic tokens describe purpose, such as background or danger. Component tokens assign semantic roles to UI parts, such as a primary button background or focus-ring outline.
Can ChromaForge update Figma directly?
The current app exports Figma Variables JSON for handoff. It is shaped for a Figma plugin or automation workflow, but ChromaForge does not yet perform direct live sync into a Figma file.
Why do I need 8-11 stops?
You can use fewer stops, but 8-11 gives the mapper enough scale resolution for ramps, Tailwind-style output, semantic surfaces, borders, and accents.
What does the CLI do that the app does not?
The CLI is meant for automation. The app helps create and repair color systems visually; the CLI can fail a build when exported files contain color pairs that do not meet AA contrast. On Mac, use Tools > CLI Utility for common commands or Tools > Copy CLI Audit Command for a starter audit command.
What changed in the Mac app?
The Mac app now opens at a practical desktop size, supports reliable two-finger trackpad scrolling in the detail editor, provides visible Close buttons on sheets, and adds View, Tools, and Help menu commands for workflow navigation and reference.
Glossary
This glossary covers the standards, acronyms, color models, token terms, export targets, and ChromaForge-specific concepts used in the app.
| Term | Meaning |
|---|---|
| A | The lowest WCAG conformance level. ChromaForge focuses its contrast pass/fail language mostly on AA and AAA. |
| AA | WCAG conformance level commonly used as a production accessibility target. For contrast in ChromaForge, AA normal text means 4.5:1 or higher; large text and non-text UI contrast use 3:1 targets. |
| AAA | Stricter WCAG conformance level. ChromaForge reports AAA text contrast at 7:1 or higher. |
| Accent | A semantic color used for links, focus rings, expressive highlights, or supporting emphasis. |
| Alpha | Opacity channel in formats such as RGBA, HSLA, and 8-digit hex. ChromaForge imports alpha-capable syntax but stores solid RGB stops in the current palette model. |
| Android XML | Android resource format where colors are exported as <color name="...">#RRGGBB</color> entries. |
| Adobe ASE | Adobe Swatch Exchange. ChromaForge imports ASE swatches with RGB, CMYK, Lab, or grayscale entries. |
| APCA | Accessible Perceptual Contrast Algorithm. A perceptual contrast/readability model shown experimentally in ChromaForge as Lc-style readings. |
| ARGB | Alpha, Red, Green, Blue integer color notation. ChromaForge uses ARGB hex strings for Compose and Flutter exports, with alpha set to FF. |
| Audit Finding | A pass, warning, or failure in the System Audit panel. |
| Auto-Fix AA | Pro repair action that adjusts failing semantic foreground colors toward WCAG AA contrast against their backgrounds. |
| Background | Semantic role for the base app or page canvas. |
| Border | Semantic role for dividers, outlines, subdued copy, grids, and UI boundaries. |
| CIELAB | CIE Lab color space. ChromaForge uses CSS-compatible D50 Lab math for lab() import, diagnostics, and Adobe ASE Lab swatches. |
| CIELCH | Cylindrical form of CIELAB using Lightness, Chroma, and Hue. ChromaForge exposes it as CSS lch(). |
| Chroma | Color intensity in OKLCH. Higher chroma means a more vivid color; lower chroma moves toward gray. |
| CI | Continuous Integration. Automated workflows that can run ChromaForge CLI audits when code changes. |
| CLI | Command-Line Interface. ChromaForge includes chromaforge-cli.swift for contrast auditing files outside the app. |
| Color Compiler | ChromaForge's core model: source colors are normalized, analyzed, mapped, and emitted as production assets. |
| Color Gamut | The range of colors a color space, display, or output device can represent. Display-P3 is wider than sRGB. |
| Color Space | A system for representing colors. ChromaForge works with sRGB, Display-P3, RGB, CIELAB, CIELCH, OKLab, and OKLCH representations. |
| Color Vision Simulation | Preview modes that transform palette colors to approximate protanopia, deuteranopia, or tritanopia. |
| color(display-p3 ...) | CSS Color syntax for specifying Display-P3 colors via the color() function. |
| color-mix() | Modern CSS function for mixing colors in a chosen color space. ChromaForge Modern CSS exports include helper variables using it. |
| ColorScheme | Flutter theme object. ChromaForge exports light and dark Flutter ColorScheme definitions. |
| Component Preview Lab | Pro preview showing buttons, fields, cards, badges, navigation, charts, dialogs, status lists, and code surfaces using compiled tokens. |
| Component Token | A token that maps a semantic role to a component use case, such as button primary background or input focus border. |
| Compose | Jetpack Compose, Android's declarative UI framework. ChromaForge exports Material 3-style Compose color schemes. |
| Contrast Ratio | WCAG 2.x ratio based on relative luminance. ChromaForge uses it for AA, AAA, large text, and non-text checks. |
| CSV | Comma-Separated Values. ChromaForge can import simple CSV palette rows and exports stop data in spreadsheet-friendly rows. |
| CSS | Cascading Style Sheets, the styling language of the web. ChromaForge imports CSS color syntax and exports several CSS formats. |
| CSS Color 4 | W3C CSS color specification level that includes HSL, HWB, Lab/LCH, OKLab/OKLCH, predefined color spaces, and color(display-p3 ...). |
| CSS Color 5 | W3C draft extending CSS color features with functions such as color-mix() and light-dark(). |
| CSS Variables | Custom properties such as --color-primary. ChromaForge exports raw, semantic, modern, Tailwind, and shadcn variable formats. |
| Custom Palette | A user-created or duplicated palette. Generated palettes become custom palettes. |
| Danger | Semantic role for destructive actions, errors, and failed status states. |
| Data Viz | Role preset that maps colors to chart background, grid, labels, and series colors. |
| Delta / Distance | Perceptual difference between colors. Palette Diff uses OKLab-style distance to rank changes. |
| Deuteranopia | Green-cone color vision deficiency simulation mode. |
| Display-P3 | Wide-gamut color space common on Apple and modern displays. ChromaForge can preview and export Display-P3 strings. |
| Dithering Preview | Subtle texture overlay used to preview how dithering can reduce visible gradient banding. |
| Distribute Stops | Stop Editor command that spaces the current stops evenly from 0% to 100% while preserving visual order. |
| DTCG | Design Tokens Community Group. ChromaForge exports DTCG 2025.10-style structured color token JSON. |
| Exact LUT Preview | Preview mode that shows discrete sampled bands instead of smooth interpolation. |
| Export | Generated code or data text that can be shared out of ChromaForge. |
| Favorite | Starred palette state. Favorites sort above other palettes in the sidebar. |
| Duplicate Palette | Palette action that creates a new custom copy, gives it a unique copy name, and selects it for editing. |
| Restore Factory Palette | Action for built-in palettes that restores the original factory definition when the palette has been changed. |
| Sort Menu | Sidebar control for ordering palettes by Favorites, Newest, Oldest, Name, Most Stops, Fewest Stops, Type, Color Space, or LUT Size. |
| Undo Last Palette Change | Detail-panel command that restores the previous snapshot of the currently selected palette. The stack is scoped to the selected palette. |
| Figma Variables | ChromaForge Pro export that describes a Figma color variable collection, modes, primitive colors, semantic colors, component aliases, code syntax, and resolved values. |
| Flutter | Google's cross-platform UI framework. ChromaForge exports Dart light and dark ColorScheme objects. |
| File Import | Import path for local palette and color files, including Mandelbrot Metal JSON, ChromaForge JSON, design-token JSON, CSS/Sass/text, CSV, GIMP GPL, and Adobe ASE. |
| Foreground | Semantic role for primary text and icons. |
| Free Export Counter | Free plan usage counter for the 5 included basic exports. It advances when a free JSON, Mandelbrot Metal, or CSS Variables export is shared. |
| Generation Recipe | Text record describing how a palette was generated or imported. Search can match recipe text. |
| GIMP GPL | GIMP Palette format. ChromaForge imports GPL files by reading RGB rows and the optional palette name. |
| Gradient Stop | A color at a position along the palette gradient. |
| Handoff | Developer workflow where colors become tokens, framework roles, exports, and audit-ready data. |
| Hex | Hexadecimal color notation, usually #RRGGBB. ChromaForge also imports shorthand and alpha forms. |
| High Contrast | Theme variant designed for stronger separation between background, foreground, surfaces, and UI elements. |
| HSL / HSLA | Hue, Saturation, Lightness, and optional Alpha CSS notation. Supported by website import. |
| HTML | HyperText Markup Language. The website importer scans page HTML and stylesheet links for colors. |
| HWB | Hue, Whiteness, Blackness CSS color function. Supported by website import. |
| Imported Palette | A palette created from a photo, file, text source, token package, swatch file, or website. Free plan imports count toward the 5 custom/imported palette limit. |
| JSON | JavaScript Object Notation. ChromaForge uses JSON for native palettes, Mandelbrot Metal, DTCG, Tokens Studio, and Style Dictionary exports. |
| Jetpack Compose | Android declarative UI toolkit. ChromaForge exports Material 3 color schemes for Compose. |
| Lc | APCA lightness contrast value. ChromaForge shows APCA-style Lc readability previews experimentally. |
| Lab | Short name for CIELAB. In CSS, lab() expresses lightness plus red-green and blue-yellow opponent axes. |
| LCH | Short name for CIELCH. In CSS, lch() expresses CIE lightness, chroma, and hue. |
| Lightness | Perceived brightness axis in OKLab/OKLCH. ChromaForge adjusts lightness during generation and contrast repair. |
| light-dark() | CSS Color 5 function that returns a light or dark value based on the used color scheme. ChromaForge Modern CSS exports use this pattern. |
| Liquid Glass | iOS 26-inspired visual treatment used by ChromaForge panels and controls in the current app UI. |
| Locked Stop | A stop protected from harmony generation. Locked colors remain fixed while unlocked stops are regenerated. |
| LUT | Lookup Table. In ChromaForge, LUT metadata and Exact LUT preview help reason about gradient sampling and output resolution. |
| Mac App | Native macOS version of ChromaForge with menu-bar commands, document-style window sizing, trackpad-friendly detail scrolling, and Mac sheet dismissal controls. |
| Material 3 | Google's design system. ChromaForge includes Material 3-inspired role presets and Compose exports. |
| Menu Bar | macOS command area containing app-level controls. ChromaForge uses View for workflow navigation and detail display controls, Tools for CLI utility commands, and Help for the user guide and website. |
| Mandelbrot Metal JSON | Import/export format for Mandelbrot Metal palettes, including schema version, color space, stops, RGB values, and notes. |
| Modern CSS | ChromaForge export that includes hex fallbacks, OKLCH, CIELAB/CIELCH diagnostic values, Display-P3, @supports, light-dark(), and color-mix(). |
| Non-Text Contrast | WCAG concept for meaningful graphical objects and UI components such as borders, focus indicators, and status markers. ChromaForge uses 3:1 checks. |
| OKLab | Perceptual color space used by ChromaForge for interpolation, distance, and color math. |
| OKLCH | Cylindrical form of OKLab with Lightness, Chroma, and Hue. Used for generation, repair, diagnostics, and modern CSS output. |
| P3 | Short name for Display-P3. |
| Palette Depth | Number of stops in a palette. ChromaForge recommends 8-11 stops for robust scale and token mapping. |
| Palette Diff | Pro comparison tool that shows stop and semantic-token changes between two palettes. |
| Palette Kind | Library category: Built-In, Imported, or Custom. |
| Perceptual Color | Color representation intended to better match human visual perception, so equal numeric changes feel more visually even than in raw RGB. CIELAB, CIELCH, OKLab, and OKLCH are perceptual spaces used or displayed by ChromaForge. |
| Perceptual Blend | Harmony mode that blends locked colors in OKLab or generates a balanced ramp from an anchor color. |
| Primitive Token | Token created directly from a palette stop, such as palette-500. |
| Protanopia | Red-cone color vision deficiency simulation mode. |
| React Native | Framework for building native apps with React. ChromaForge exports typed theme objects for it. |
| Readiness Score | System Audit score from 0-100 based on warnings and failures. |
| Relative Luminance | Light output calculation used by WCAG contrast ratios. ChromaForge uses it for text and non-text contrast. |
| RGB / RGBA | Red, Green, Blue, and optional Alpha color notation. Supported by imports and internal color representation. |
| Role Alias | Name from an external role system mapped to a ChromaForge semantic role. |
| Role Preset | A mapping set for ChromaForge, shadcn/ui, Material 3, Apple UI, or Data Viz roles. |
| Sass | CSS preprocessor. ChromaForge exports primitive and semantic Sass variables. |
| Semantic CSS | Export with light, dark, high-contrast, prefers-color-scheme, semantic variables, and component variables. |
| Semantic Token | Token named by purpose rather than source color, such as background, foreground, primary, or danger. |
| shadcn/ui | Component system using Tailwind and CSS variables. ChromaForge exports shadcn-compatible theme variables. |
| sRGB | Standard RGB color space used broadly across web and software tools. Best for broad compatibility. |
| Step Marker | Vertical line in the gradient preview showing the exact position of a palette stop. |
| StoreKit | Apple framework for App Store purchases and subscriptions. ChromaForge uses StoreKit 2 to load paid products, purchase verified transactions, refresh current entitlements, listen for transaction updates, and restore purchases. |
| Style Dictionary | Design-token build tool. ChromaForge exports Style Dictionary-compatible JSON. |
| Success | Semantic role for positive status and completed actions. |
| Surface | Semantic role for cards, panels, and grouped UI backgrounds. |
| Surface Raised | Semantic role for elevated surfaces such as popovers, dialogs, and highlighted panels. |
| Swift Assets | Export guide for creating Apple asset-catalog color sets for light, dark, and high-contrast variants. |
| SwiftUI | Apple declarative UI framework. ChromaForge exports Color extension code. |
| Tailwind | Utility-first CSS framework. ChromaForge exports classic Tailwind config and Tailwind v4 @theme CSS. |
| Theme Matrix | Developer Handoff overview of light, dark, and high-contrast variants with role swatches and AA coverage. |
| Theme Variant | A compiled color mode: Light, Dark, or High Contrast. |
| Variable Mode | Figma Variables concept that lets one variable hold different values for modes such as Light, Dark, and High Contrast. |
| Token | A named design value used by code and design systems. ChromaForge produces primitive, semantic, component, and framework-specific tokens. |
| Tokens Studio | Design-token workflow associated with Figma. ChromaForge exports Tokens Studio-style JSON. |
| Tritanopia | Blue-cone color vision deficiency simulation mode. |
| UI | User Interface. |
| WCAG | Web Content Accessibility Guidelines from W3C. ChromaForge uses WCAG 2.2 contrast thresholds for accessibility checks. |
| Website Import | Importer that scans HTML, inline styles, and linked CSS for colors, ranks likely brand/theme colors, and creates an imported palette. |
| Wide Gamut | Color range wider than sRGB, such as Display-P3. Wide-gamut colors can look richer on supported displays. |
| Workflow Surface | Top-level ChromaForge command area with Source, Forge, Validate, and Ship stages. |
| XML | Extensible Markup Language. ChromaForge uses XML for Android color resource export. |
Standards & References
These references inform the standards and terminology used in this guide.