solarized-emacs

README.md (14489B)

---

 [![License GPL 3][badge-license]](http://www.gnu.org/licenses/gpl-3.0.txt)
 [![MELPA](http://melpa.org/packages/solarized-theme-badge.svg)](http://melpa.org/#/solarized-theme)
 [![MELPA Stable](http://stable.melpa.org/packages/solarized-theme-badge.svg)](http://stable.melpa.org/#/solarized-theme)
 
 # Solarized for Emacs
 
 Solarized for Emacs is an Emacs 24bit theme making use of the
 [Solarized palette](http://ethanschoonover.com/solarized), developed by Ethan Schoonover.
 
 Here are the two canonical variants:
 
 <table>
   <tr>
     <td align="center"><code>solarized-dark</code><br><img src="screenshots/solarized-dark.png" alt="solarized-dark" width="440"></td>
     <td align="center"><code>solarized-light</code><br><img src="screenshots/solarized-light.png" alt="solarized-light" width="440"></td>
   </tr>
 </table>
 
 You can find some more screenshots of Solarized for Emacs
 [here](https://emacsthemes.com/themes/solarized-themes.html).
 
 Solarized for Emacs supports officially Emacs 24+. The theme is implemented
 in terms of customisations and `deftheme` and does not require the
 `color-theme-package`.
 
 ## Installation
 
 Solarized for Emacs is available for installation via the
 [MELPA](http://melpa.org) using `package.el`.  Assuming you've set it
 up you can install Solarized like this:
 
 `M-x package-install solarized-theme`
 
 This package will install two variants of the theme; `solarized-light-theme`
 and `solarized-dark-theme`. You can load one of the theme variants with `M-x
 load-theme`.
 
 To load it automatically on Emacs startup add this to your init file:
 
 ```emacs-lisp
 (load-theme 'solarized-light t)
 ```
 
 or
 
 ```emacs-lisp
 (load-theme 'solarized-dark t)
 ```
 
 You can toggle between the light and dark variant of the theme automatically with
 `M-x solarized-toggle-theme`.
 
 ## Alternative Palettes
 
 In addition to `solarized-dark` and `solarized-light`, the package ships the
 following theme variants:
 
 - `solarized-dark-high-contrast` / `solarized-light-high-contrast`
 - `solarized-gruvbox-dark` / `solarized-gruvbox-light`
 - `solarized-selenized-dark` / `solarized-selenized-light` / `solarized-selenized-black` / `solarized-selenized-white`
 - `solarized-zenburn`
 - `solarized-wombat-dark`
 
 <table>
   <tr>
     <td align="center"><code>solarized-dark-high-contrast</code><br><img src="screenshots/solarized-dark-high-contrast.png" alt="solarized-dark-high-contrast" width="380"></td>
     <td align="center"><code>solarized-light-high-contrast</code><br><img src="screenshots/solarized-light-high-contrast.png" alt="solarized-light-high-contrast" width="380"></td>
   </tr>
   <tr>
     <td align="center"><code>solarized-gruvbox-dark</code><br><img src="screenshots/solarized-gruvbox-dark.png" alt="solarized-gruvbox-dark" width="380"></td>
     <td align="center"><code>solarized-gruvbox-light</code><br><img src="screenshots/solarized-gruvbox-light.png" alt="solarized-gruvbox-light" width="380"></td>
   </tr>
   <tr>
     <td align="center"><code>solarized-selenized-dark</code><br><img src="screenshots/solarized-selenized-dark.png" alt="solarized-selenized-dark" width="380"></td>
     <td align="center"><code>solarized-selenized-light</code><br><img src="screenshots/solarized-selenized-light.png" alt="solarized-selenized-light" width="380"></td>
   </tr>
   <tr>
     <td align="center"><code>solarized-selenized-black</code><br><img src="screenshots/solarized-selenized-black.png" alt="solarized-selenized-black" width="380"></td>
     <td align="center"><code>solarized-selenized-white</code><br><img src="screenshots/solarized-selenized-white.png" alt="solarized-selenized-white" width="380"></td>
   </tr>
   <tr>
     <td align="center"><code>solarized-zenburn</code><br><img src="screenshots/solarized-zenburn.png" alt="solarized-zenburn" width="380"></td>
     <td align="center"><code>solarized-wombat-dark</code><br><img src="screenshots/solarized-wombat-dark.png" alt="solarized-wombat-dark" width="380"></td>
   </tr>
 </table>
 
 The intent of this theme will always be that Solarized-dark/light will give you
 the best possible experience. Palettes other than Solarized will never have
 influence over theming decisions, they are complementary.
 
 You should not expect the complementary themes to be fully accurate or the most
 suitable versions of how to apply those palettes into an emacs theme. The
 important aspect is that the color usage should be about the same as they are
 with the default Solarized palette.
 
 Colors stand out with varying amounts depending on which palette is used. This
 theme aims for a very soft look, violet is one of the most pronounced accent
 colors in the Solarized palette and that is one reason why it's rarely used by
 the theme. Violet in another palette might stand out less and therefore be used
 more often if the theme was specifically designed with that palette in mind.
 
 The original Zenburn palette doesn't have a violet it is created by blending
 blue and magenta to get it to fit into the theme so it's tilted towards
 translating into what this theme has decided.
 
 *TLDR*; While `solarized-gruvbox-light` might be a good complement for users of
 `solarized-light`, another theme not contained in this package (`gruvbox-light`
 or whatever) might be more finely tuned in relation to the Gruvbox palette.
 
 ## Customisations
 
 ### Theme-specific settings
 
 If you don't like low-contrast modeline or fringe, you can `customize` them
 either by doing `M-x customize-group solarized` or setting the values using
 elisp code:
 
 ```emacs-lisp
 ;; make the fringe stand out from the background
 (setq solarized-distinct-fringe-background t)
 
 ;; Don't change the font for some headings and titles
 (setq solarized-use-variable-pitch nil)
 
 ;; make the modeline high contrast
 (setq solarized-high-contrast-mode-line t)
 
 ;; Use less bolding
 (setq solarized-use-less-bold t)
 
 ;; Use more italics
 (setq solarized-use-more-italic t)
 
 ;; Use less colors for indicators such as git:gutter, flycheck and similar
 (setq solarized-emphasize-indicators nil)
 
 ;; Don't change size of org-mode headlines (but keep other size-changes)
 (setq solarized-scale-org-headlines nil)
 
 ;; Change the size of markdown-mode headlines (off by default)
 (setq solarized-scale-markdown-headlines t)
 
 ;; Avoid all font-size changes
 (setq solarized-height-minus-1 1.0)
 (setq solarized-height-plus-1 1.0)
 (setq solarized-height-plus-2 1.0)
 (setq solarized-height-plus-3 1.0)
 (setq solarized-height-plus-4 1.0)
 
 ;; Highlight all numbers
 (setq solarized-highlight-numbers t)
 
 ```
 
 Note that these need to be set **before** `load-theme` is invoked for Solarized.
 Alternatively you can invoke `M-x solarized-reload` after making configuration changes.
 
 ### Overriding specific faces
 
 If you're unhappy with how a particular mode looks you can override individual
 faces after loading the theme. Use `custom-theme-set-faces` to keep your
 overrides tied to the theme, or `custom-set-faces` for global overrides.
 
 ```emacs-lisp
 ;; Override org-mode heading colors
 (custom-theme-set-faces
  'solarized-dark
  '(org-level-1 ((t (:foreground "#268bd2" :weight bold :height 1.3))))
  '(org-level-2 ((t (:foreground "#2aa198" :weight bold :height 1.2)))))
 ```
 
 ```emacs-lisp
 ;; Make markdown code blocks stand out more
 (custom-theme-set-faces
  'solarized-light
  '(markdown-code-face ((t (:background "#eee8d5" :foreground "#657b83"))))
  '(markdown-inline-code-face ((t (:background "#eee8d5" :foreground "#657b83")))))
 ```
 
 ```emacs-lisp
 ;; Tone down font-lock colors across all modes
 (custom-theme-set-faces
  'solarized-dark
  '(font-lock-keyword-face ((t (:foreground "#859900" :weight normal))))
  '(font-lock-function-name-face ((t (:foreground "#268bd2" :weight bold)))))
 ```
 
 These overrides should be placed **after** `load-theme` in your init file.
 You can discover face names at point with `M-x describe-face` or see all
 active faces with `M-x list-faces-display`.
 
 ### Buffer-local face overrides
 
 If you only want to tweak faces in certain major modes (without affecting the
 rest of Emacs), you can use `face-remap-add-relative` in a mode hook. It
 remaps a face only in the current buffer.
 
 ```emacs-lisp
 ;; Customize faces only in OCaml buffers
 (defun my-ocaml-faces ()
   (face-remap-add-relative 'font-lock-type-face :foreground "DarkGreen")
   (face-remap-add-relative 'font-lock-function-name-face :weight 'bold))
 
 (add-hook 'tuareg-mode-hook #'my-ocaml-faces)
 ```
 
 ```emacs-lisp
 ;; Use a larger default font in org-mode
 (defun my-org-faces ()
   (face-remap-add-relative 'default :height 1.2))
 
 (add-hook 'org-mode-hook #'my-org-faces)
 ```
 
 See [Buffer-Local Face Remapping with face-remap-add-relative](https://emacsredux.com/blog/2026/03/16/buffer-local-face-remapping-with-face-remap-add-relative/)
 for more details and advanced usage (toggling remappings, wrapping them in minor modes, etc.).
 
 ### Underline position setting for X
 
 If you are using Emacs under X you might like the following setting which puts
 the underline below the
 [font bottomline instead of the baseline](https://stackoverflow.com/questions/27631736/meaning-of-top-ascent-baseline-descent-bottom-and-leading-in-androids-font).
 
 Imho it enhances the general readability and also it fits well with the default
 `solarized-high-contrast-mode-line` setting which uses a slightly emphasized
 underline for the modeline to create one horizontal window border in the same
 manner as the vertical border.
 
 ```emacs-lisp
 (setq x-underline-at-descent-line t)
 ```
 
 ## Custom Themes
 
 You can create your own theme that reuses all of Solarized's face definitions
 but with a different color palette. You provide 10 colors -- a darkest base, a
 brightest base, and 8 accents (yellow, orange, red, magenta, violet, blue, cyan,
 green) -- and the theme framework derives all the intermediate shades and
 highlight variants automatically.
 
 ### Creating a theme from a custom palette
 
 Call `solarized-create-theme-file-with-palette` in your init file. It generates
 a theme file in `~/.emacs.d/themes/` that you can then load normally.
 
 ```emacs-lisp
 ;; inspired by vim's jellybeans color-theme
 (solarized-create-theme-file-with-palette 'light 'solarized-jellybeans-light
   '("#202020" "#ffffff"
     "#ffb964" "#8fbfdc" "#a04040" "#b05080" "#805090" "#fad08a" "#99ad6a" "#8fbfdc"))
 
 (load-theme 'solarized-jellybeans-light t)
 ```
 
 ```emacs-lisp
 ;; inspired by emacs's mesa color-theme
 (solarized-create-theme-file-with-palette 'light 'solarized-mesa-light
   '("#000000" "#faf5ee"
     "#3388dd" "#ac3d1a" "#dd2222" "#8b008b" "#00b7f0" "#1388a2" "#104e8b" "#00688b"))
 
 (load-theme 'solarized-mesa-light t)
 ```
 
 You can also override individual faces by passing a sexp as the fourth argument.
 This lets you tweak specific faces while still inheriting everything else from
 the palette:
 
 ```emacs-lisp
 ;; wombat palette with custom face overrides
 (solarized-create-theme-file-with-palette 'dark 'solarized-wombat-dark
   '("#2a2a29" "#f6f3e8"
     "#e5c06d" "#ddaa6f" "#ffb4ac" "#e5786d" "#834c98" "#a4b5e6" "#7ec98f" "#8ac6f2")
   '((custom-theme-set-faces
      theme-name
      `(default ((,class (:foreground ,(solarized-color-blend base03 base3 0.15 2) :background ,base03))))
      `(highlight ((,class (:background ,violet))))
      `(font-lock-builtin-face ((,class (:foreground ,magenta))))
      `(font-lock-constant-face ((,class (:foreground ,blue))))
      `(font-lock-comment-face ((,class (:foreground ,base00))))
      `(mode-line
        ((,class (:foreground ,base2 :background ,(solarized-color-blend base03 base3 0.85 2)))))
      `(mode-line-inactive
        ((,class (:foreground ,base00 :background ,(solarized-color-blend base03 "black" 0.85 2)))))
      `(mode-line-buffer-id ((,class (:foreground ,base3 :weight bold))))
      `(minibuffer-prompt ((,class (:foreground ,base1))))
      `(vertical-border ((,class (:foreground ,base03)))))))
 
 (load-theme 'solarized-wombat-dark t)
 ```
 
 **Note:** If the theme file already exists, `solarized-create-theme-file` does not
 regenerate it. Pass `t` as the fifth argument to overwrite.
 
 ### Child themes
 
 If you want to keep the Solarized palette but override specific faces
 consistently across dark and light variants, you can create a child theme. This
 is useful when you like Solarized's colors but want to adjust how certain
 modes look.
 
 Define your face overrides in a shared file:
 
 ```emacs-lisp
 ;; my-solarized.el
 (defvar my-solarized-faces
   '("My personal solarized customizations."
     (custom-theme-set-faces
      theme-name
      `(rainbow-delimiters-depth-1-face ((,class (:foreground ,base02))))
      `(org-level-1 ((,class (:foreground ,blue :weight bold)))))))
 
 (provide 'my-solarized)
 ```
 
 Then create thin wrapper files for each variant (place these on your
 `custom-theme-load-path`):
 
 ```emacs-lisp
 ;; themes/my-solarized-dark-theme.el
 (require 'solarized)
 (require 'my-solarized)
 (eval-when-compile
   (require 'solarized-palettes))
 
 (deftheme my-solarized-dark "My dark Solarized child theme")
 (solarized-with-color-variables
   'dark 'my-solarized-dark solarized-dark-color-palette-alist my-solarized-faces)
 
 (provide-theme 'my-solarized-dark)
 ```
 
 ```emacs-lisp
 ;; themes/my-solarized-light-theme.el
 (require 'solarized)
 (require 'my-solarized)
 (eval-when-compile
   (require 'solarized-palettes))
 
 (deftheme my-solarized-light "My light Solarized child theme")
 (solarized-with-color-variables
   'light 'my-solarized-light solarized-light-color-palette-alist my-solarized-faces)
 
 (provide-theme 'my-solarized-light)
 ```
 
 Your face overrides have access to all palette variables (`base03`, `base0`,
 `yellow`, `blue`, etc.) and all derived variables (`s-fringe-bg`,
 `s-mode-line-fg`, etc.). See the
 [child-theme-example](child-theme-example/) directory for a working example.
 
 ## Versioning Policy
 
 - This package uses [semantic versioning](https://semver.org/)
 
 - Master branch is to be considered unstable (which isn't an excuse to
   constantly break behaviour). Use MELPA Stable if you want fewer breaking
   changes.
 
 ## Bugs & Improvements
 
 Please, report any problems that you find on the projects integrated
 issue tracker. If you've added some improvements and you want them
 included upstream don't hesitate to send me a patch or even better - a
 GitHub pull request.
 
 ## License
 
 Copyright © 2011-2026 Bozhidar Batsov, [Thomas Frössman](http://t.jossystem.se), and
 [contributors](https://github.com/bbatsov/solarized-emacs/contributors).
 
 Distributed under the GNU General Public License, version 3
 
 [badge-license]: https://img.shields.io/badge/license-GPL_3-green.svg