A package to display colors in project and files:
Pigments will scan source files in your project directories looking for colors and will build a palette with all of them. Then for each opened file, it will use the palette to evaluate the value of a given color. The legible source paths can be defined through various settings either at the global or per project level. By default colors in every file will be highlighted, to limit the display of colors to the desired filetype only please see the Defining Where Pigments Applies below.
Pigments supports out of the box most of the color transformations functions and expressions of the three biggest CSS pre-processors out there, namely LESS, Sass and Stylus. However, it doesn't mean pigments is able to parse and understand all of these languages constructs. For the moment, Pigments' aim is to support the widest range of usage, even if it implies reducing its ability to parse certain complex constructs. You can refer to the parser specs for an exhaustive list of the supported expressions.
This is a small note from one of the contributors. As of the time of writing, @abe33 (the creator of this amazing package) hasn't done any work on this repo for over 6 months. It seems he is focused on other projects. In the meantime, I've been trying to keep the issues clear and tagged and to close duplicates. However, I don't know enough about this project (or Atom plugins in general) to be able to fix any issues. If you think you are able to handle this project, please let me (@C-Bouthoorn) or Cédric (@abe33) know, so we could help you help this project.
Please also see this masterpost.
Using apm
:
apm install pigments
Or search for pigments
in Atom settings view.
By default, Pigments will highlight every color in every file, but you can limit that using the two settings Supported Filetypes
and Ignored Scopes
.
The first setting allow you to specify the list of extensions where pigments will apply. For instance, by using the values css, less
, colors will be visible only in CSS and Less files.
The second setting takes an array of regular expression strings used to exclude colors in specific scopes (like comments or strings). You can find the scope that applies at the cursor position with the Editor: Log Cursor Scope
command (cmd-alt-p or ctrl-alt-shift-p).
Pigments is able to follow variables uses up to a certain point, if a color refers to several variables whose values can't be evaluated (because they use unsupported language-specific features) the color will be flagged as invalid and not displayed. This can be problematic when it happens on the core components of a complex palette.
To solve that issue, you can define a defaults file named .pigments
at the root of a project directory and you can put in it all the variables declarations to use if a value from the sources files can't be evaluated.
This can also be used when your project core palette is dynamically defined so that pigments can evaluate properly the rest of the project colors.
Note: Pigments doesn't define any keybindings for the provided commands, instead it'll let you define your own keybindings.
You can display the project's palette through the Pigments: Show Palette
command from the command palette:
The project palette is made of all the colors that are affected to a variable, which means it won't display hardcoded colors affected to a CSS property. If you want to find every color used in a project, including the hardcoded colors in CSS files, use the Pigments: Find Colors
instead.
Patterns for Less, Sass, Scss and Stylus variables are currently supported, which includes:
my-var = #123456 // stylus
$my-var: #123456 // sass
$my-var: #123456; // scss
@my-var: #123456; /* less */
As with every command, this command can be triggered using the keyboard by defining a keybinding like this:
'atom-workspace':
'alt-shift-p': 'pigments:show-palette'
You can search for all colors in your project using the Pigments: Find Colors
command from the command palette:
The results will include colors declared in variables, places where the color variables are used as well as hardcoded color values in every file that matches one of the patterns defined in both pigments.sourceNames
and pigments.extendedSearchNames
settings.
By default this includes:
**/*.css
**/*.less
**/*.scss
**/*.sass
**/*.styl
**/*.stylus
This command can be triggered using the keyboard by defining a keybinding like this:
'atom-workspace':
'alt-shift-f': 'pigments:find-colors'
It evaluates and replace a color by the corresponding notation. Accessible from the command palette or by right clicking on a color.
These commands can be triggered using the keyboard by defining a keybinding like this:
'atom-workspace':
'alt-shift-h': 'pigments:convert-to-hex'
'alt-shift-g': 'pigments:convert-to-rgb'
'alt-shift-j': 'pigments:convert-to-rgba'
'alt-shift-k': 'pigments:convert-to-hsl'
'alt-shift-l': 'pigments:convert-to-hsla'
When triggered from the command palette or from the keyboard, the conversion will operate on every cursor positioned on color markers.
Each Pigments project has its own set of settings that can extend or replace the global configuration. These settings are available through the pigments:project-settings
command:
The Source Names
, Ignored Names
, Ignored Scopes
and Extended Search Names
fields all match a global configuration. When defined the project will use both the global config and the one of the current project, except when the Ignore Global
checkbox is checked.
The Include Atom Themes Stylesheets
setting is specific to the project and can't be defined globally. When enabled, it'll add all the public themes variables in the current project palette:
Note that it won't add all the variables defined in the less files of the syntax and ui themes, only the ones that must be present as defined in the themes documentation.
This feature is still quite experimental at this stage.
This command will force a reload of all variables in the project, this can be useful when the serialized state of the plugin contains invalid data and you want to get rid of them without having to touch to the content of the .atom/storage
directory.
This command can be triggered using the keyboard by defining a keybinding like this:
'atom-workspace':
'alt-shift-r': 'pigments:reload'
An array of glob patterns of the files to use as source for the project's variables and colors.
- Key:
pigments.sourceNames
- Default:
['**/*.styl', '**/*.stylus', '**/*.less', '**/*.sass', '**/*.scss']
An array of glob patterns of the files to ignore as source files for the project's variables and colors.
- Key:
pigments.ignoredNames
- Default:
['node_modules/*']
An array of glob patterns of files to include in the Pigments: Find Colors
scanning process.
- Key:
pigments.extendedSearchNames
- Default:
['**/*.css']
An array of file extensions where colors will be highlighted. If the wildcard *
is present in this array then colors in every file will be highlighted.
- Key:
pigments.supportedFiletypes
- Default:
['*']
An array of file extensions where color values such as red
, azure
or whitesmoke
will be highlighted. By default CSS and CSS pre-processors files are supported.
You can use none
or whatever value that doesn't match a file extension to completely prevent color words from being highlighted.
- Key:
pigments.filetypesForColorWords
- Default:
['css', 'less', 'styl', 'stylus', 'sass', 'scss']
An array of regular expressions strings to match scopes to ignore when rendering colors in a text editor.
For instance, if you want to ignore colors in comments and strings in your source files, use the following value:
\.comment, \.string
As you can notice, the .
character in scopes are escaped. This is due to the fact that this setting uses javascript RegExp
to test the token's scope and the .
is used to match against any character.
For instance, to ignore colors in html attributes you can use the following expression:
\.text\.html(.*)\.string
Note the (.*)
in the middle of the expression. It'll ensure that we're searching for the .string
scope in the .text.html
grammar even if there's other scope between them by catching any character between the two classnames.
To find which scope is applied at a given position in a buffer you can use the editor:log-cursor-scope
command. From that you'll be able to determine what expression to use to match the scope.
- Key:
pigments.ignoredScopes
- Default:
[]
The autocomplete provider will only complete color names in editors whose scope is present in this list.
- Key:
pigments.autocompleteScopes
- Default:
['.source.css', '.source.css.less', '.source.sass', '.source.css.scss', '.source.stylus']
Sass doesn't provide any implementation for shade and tint function, and Compass and Bourbon have different implementation for these two methods. This setting allow you to chose which implementation to use.
- Key:
pigments.sassShadeAndTintImplementation
- Default:
'compass'
When enabled, the autocomplete provider will also provides completion for non-color variables.
- Key:
pigments.extendAutocompleteToVariables
- Default:
false
When enabled, the autocomplete provider will also provides color value.
- Key:
pigments.extendAutocompleteToColorValue
- Default:
false
Whether to traverse symlinked directories to find source files or not.
- Key:
pigments.traverseIntoSymlinkDirectories
- Default:
false
When this setting is enabled, every file that are ignored by the VCS will also be ignored in Pigments. That means they'll be excluded when searching for colors and when building the project palette.
- Key:
pigments.ignoreVcsIgnoredPaths
- Default:
true
Defines the render mode of color markers. The possible values are:
background | outline | underline |
---|---|---|
|
|
|
dot | square-dot | gutter |
|
|
|
- Key:
pigments.markerType
- Default:
'background'
The type of sorting applied to the colors in the palette view. It can be changed directly from the palette view.
- Key:
pigments.sortPaletteColors
- Default:
'none'
Defines how the colors are grouped together in the palette view. It can be changed directly from the palette view.
- Key:
pigments.groupPaletteColors
- Default:
'none'
Defines whether to merge colors duplicates together as a single result in the palette view. It can be changed directly from the palette view.
- Key:
pigments.mergeDuplicates
- Default:
false
Pigments rescans the text buffer once you stopped editing it, however as the process can be sometime expensive, it'll apply an extra delay after the dispatch of the did-stop-changing
event before starting the scanning process. This setting define the number of milliseconds to wait after the did-stop-changing
event before starting to scan the buffer again. If your start typing in the buffer again in this interval, the rescan process will be aborted.
- Key:
pigments.delayBeforeScan
- Default:
500
(ms)