CSScheme - Sublime Text Plugin

Ever thought handwriting .tmTheme files sucks? But the other options for editing color schemes are not programmatical enough? Then this is for you!

CSScheme is a custom CSS-like syntax that converts into the .tmTheme files we all love, but it does not end there. CSScheme (the package) can also take care of compiling SCSS, SASS or stylus into CSScheme (the syntax) and then into a color scheme using all features of these pre-compilers, such as variables, conditionals or functions.

Check the example files for what's possible!

Installation

Use Package Control to install "CSScheme".

Usage (Please Read!)

You can either create a new file with the CSScheme: Create new *Scheme file commands, open a file with the .csscheme, .scsscheme, .sasscheme or .styluscheme extension or convert an existing tmTheme file using the CSScheme: Convert to CSScheme command or build system. Conversion to other syntaxes is not supported at the moment and likely won't in the future. Please convert manually and to your own preferences.

Building (ctrl+b or ⌘b) will convert the file to CSScheme, if necessary, and then into a .tmTheme file. Errors during conversion are captured in an output panel. For automation purposes, the command is named convert_csscheme.

Things you must consider when using CSScheme:

• @ at-rules will be added as string values to the "outer dictionary". You may specify a global @name rule to specify the scheme's name. @name rules in a ruleset will show as the name for various color scheme editing tools after compilation. Sublime Text itself does not use it.
• In order to create a .hidden-tmTheme file, you need to specify a global @hidden true; rule. The converter will consume this rule and change the output file's extension accordingly.
• If you want a property to have no font styles you have to specify fontStyle: none;. This will be translated to <key>fontStyle</key><string />.
• The general settings (like main background color) are read from a general- purpose block with a * selector. This is required.
• Specifying a uuid (via @uuid) is optional because Sublime Text ignores it.

Things you must consider additionally when using CSScheme with SCSS or SASS:

• Make sure that sass is available on your PATH or adjust the path to the executable in the settings.

• The SASS parser will not accept raw #RRGGBBAA hashes. You must enclose them in a string, e.g. '#12345678', or just use the rgba() notation.

• The SASS parser will also not work with several scope selector operators (-, &, (, ), |). You must escape these with a backslash. The same applies to scope-segments starting with a number.

  CSScheme will take care of removing backslashes before emitting the final conversion result. Examples can be found in the example files).

  Note: Because the SASS parser does not know about the semantics of these operators, they will generally behave poorly when used in conjunction with scope nesting.

Things you must consider additionally when using CSScheme with stylus:

• Make sure that stylus is available on your PATH or adjust the path to the executable in the settings.
• At-rules, like the required global @name must be encapsulated with unquote(). Example: unquote('@name "Example StyluScheme";')
• At-rules in non-global scope do not work! You'd only need these for @name or possibly @comment anyway, but stylus does some weird stuff that does not translate into sane CSScheme.

Supported Syntaxes

CSScheme (the package) provides native support for CSScheme-to-.tmTheme conversion. Thus, all languages that compile to CSS will also work in one way or another. SCSS/SASS and stylus are automatically built from within Sublime Text, and SCSScheme even has its own syntax definition because the one from the SCSS package highlights unknown properties as invalid. Furthermore they provide snippets and completions.

• Syntax highlighting for CSScheme and SCSScheme is bundled. Snippets and completions are provided for both.
• For SASScheme syntax highlighting you additionally need the Sass package.
• For StyluScheme syntax highlighting you additionally need the Stylus package.

If you want to use something a different pre-processor, you can do so by converting to CSScheme externally and then do conversion from CSScheme to tmTheme from within Sublime Text. Feel free to file an issue (if there isn't one already) if you'd like built-in support for an additional pre-processor.

Utility for Scheme Creation

(only CSScheme and SCSScheme)

Symbol List

Just press ctrl+r (⌘r).

In StyluScheme this is somewhat supported but since scope names are not regular html tags they don't get recognized (since I didn't bother to write a new syntax definition for stylus as well).

Snippets

• * (* ruleset)
• r (general purpose ruleset)

only SCSScheme:

• mixin, = (short for mixin)
• if, elif, else
• for (from ... to), fort (from ... through)
• each
• while

Completions

All known properties are completed as well as the basic scopes from the Text Mate scope naming conventions when specifying a selector.

Useful Resources

Here is a bunch of links that might help you when working on your color scheme.

• TextMate Manual - Scope Selectors

• TextMate Manual - Scope Naming Conventions

• SASS/SCSS

• SASS (color) function reference

• Overview of SASS functions with example colors

• stylus reference

• HSL to RGB converter

• Color Scheme Calculator

• Hue scales using HCL

• Multi-hued color scales

• Tool for multi-hued color scales

Example Files

I prepared two example files that are merely a proof of concept and show a few of the features that are supported. The colors itself don't make much sense and are not good on the eyes because I picked them pretty much randomly, but it gives some great insight on what is possible.

• [Example SCSScheme.scsscheme](./Example SCSScheme.scsscheme)
• [Example StyluScheme.scsscheme](./Example StyluScheme.styluscheme)

If you would like to see a real world example, refer to the Writerly Scheme by @alehandrof which heavily uses SASS's @import to make a larger scheme more manageable.

Other Efforts for Easing Color Scheme Creation

Please note that all these work directly on .tmTheme files.

• https://github.com/facelessuser/ColorSchemeEditor/ - Cross platform Python application for editing color schemes in a GUI
• https://github.com/nilium/schemer - OS X App, similar to the above
• http://tmtheme-editor.herokuapp.com/ - Webapp, similar to the above but with a bunch of example color schemes to preview/edit and a nice preview
• https://github.com/bobef/ColorSchemeEditor-ST2 - Sublime Text plugin that syncronizes