{"id":18862693,"url":"https://github.com/zk-phi/elemental-theme","last_synced_at":"2025-07-17T19:38:23.710Z","repository":{"id":152679627,"uuid":"130332334","full_name":"zk-phi/elemental-theme","owner":"zk-phi","description":"WIP An elemental theme","archived":false,"fork":false,"pushed_at":"2024-05-02T15:20:44.000Z","size":3901,"stargazers_count":20,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-05-30T16:36:02.887Z","etag":null,"topics":["emacs"],"latest_commit_sha":null,"homepage":"","language":"Emacs Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zk-phi.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-04-20T08:21:24.000Z","updated_at":"2024-05-10T04:20:01.000Z","dependencies_parsed_at":null,"dependency_job_id":"5fce20d0-a603-4580-92fd-7e2f9d2287f3","html_url":"https://github.com/zk-phi/elemental-theme","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zk-phi%2Felemental-theme","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zk-phi%2Felemental-theme/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zk-phi%2Felemental-theme/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zk-phi%2Felemental-theme/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zk-phi","download_url":"https://codeload.github.com/zk-phi/elemental-theme/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223634005,"owners_count":17176871,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["emacs"],"created_at":"2024-11-08T04:35:30.514Z","updated_at":"2024-11-08T04:35:31.176Z","avatar_url":"https://github.com/zk-phi.png","language":"Emacs Lisp","readme":"## Elemental-theme\n\nAn Emacs color theme well organized with the built-in inheritance\nmechanism.\n\nMeant to be ...\n\n### 1. Easy to customize\n\nYou choose colors. `elemental-theme` maps the colors to faces.\n\n![Screencast](img/screencast.gif)\n\n### 2. Consistent\n\nSame meaning, same look. Designed to be intuitive.\n\n![Consistency](img/consistency.png)\n\n## Installation\n\nAdd elemental-theme.el to the load-path, and enable the theme.\n\n```\n(require 'elemental-theme)\n(enable-theme 'elemental-theme)\n```\n\n### Recommended settings\n\nIt's recommended to enable `window-divider-mode`, so that\nelemental-theme can change the color of vertical window divider.\n\n```\n(window-divider-mode 1)\n```\n\n## Customization\n\nFollowing faces are called \"elemental\" in this theme.\n\nAll other supported faces are derived from these faces, so you can\neasily create your own look by just editing these \"elemental\" faces.\n\nYou may use `M-x describe-face` for more detailed descriptions of each\nfaces.\n\nCore faces:\n\n- `default` (built-in)\n- `cursor` (built-in)\n\nBrightness variations:\n\n- `elemental-bright-bg-face`\n- `elemental-brighter-bg-face`\n- `elemental-bright-fg-face`\n- `elemental-dark-fg-face`\n- `elemental-darker-fg-face`\n\nAccents:\n\n- `elemental-accent-fg-1-face`\n- `elemental-accent-fg-2-face`\n- `elemental-accent-fg-3-face`\n- `elemental-accent-fg-4-face`\n\nColor-specific faces:\n\n- `elemental-red-fg-face`\n- `elemental-blue-fg-face`\n- `elemental-green-fg-face`\n- `elemental-orange-fg-face`\n\nTo customize these elemental faces, functions like\n`set-face-background`, `set-face-foreground` and `set-face-attribute`\nare useful.\n\n``` emacs-lisp\n;; 'red' means '#ff3333' in this face\n(set-face-foreground 'elemental-red-fg-face \"#ff3333\")\n```\n\nFollowing faces are considered \"elemental\" too, but you usually don't\nneed to modify:\n\n- `bold` (built-in)\n- `italic` (built-in)\n- `underline` (built-in)\n- `elemental-red-underline-face`\n- `elemental-yellow-underline-face`\n- `elemental-inverse-video-face`\n\n### Naming conventions\n#### `-fg-` faces and `-bg-` faces\n\nIf an elemental face contains `-fg-` in its name, it's considered a\n\"foreground face\". `-bg-` stands for \"background\" face respectively.\n\nYou usually want to set a foreground color for a foreground face, and\na background color for a background face:\n\n``` emacs-lisp\n(set-face-background 'elemental-bright-bg-face \"#222233\")\n(set-face-foreground 'elemental-brighter-fg-face \"#ffffff\")\n```\n\n`elemental-theme` does not use more than one foreground faces (or\nbackground faces) for the same part of a text. But `elemental-theme`\nmay combine one foreground face and one background face together for\nthe same part of a text. You may put any styles for \"elemental\" faces,\nbut foreground faces should not conflict with any other background\nfaces (and vice-versa).\n\n#### Color-specific faces\n\nSome elemental faces contain specific color names in their face names\n(like `elemental-red-fg-face`).\n\nIn the context of user interfaces, some colors may imply special\nmeanings:\n\n- red ... danger, error, deletion, inhibited etc\n- yellow ... warning, change etc\n- green ... safe, success, addition etc\n- blue ... information, allowed etc\n\nIf an elemental face contains a specific color name,\n`elemental-red-fg-face` for an example, it is usually expected to look\nreddish and used to highlight erorrs etc.\n\nIf you have a reddish color in `accent-*` faces, it's okay to reuse\nthe color:\n\n``` emacs-lisp\n;; `accent-1' face is reddish in our theme, so reuse the color for `red` face too\n(set-face-foreground 'elemental-red-face (face-foreground 'elemental-accent-fg-1-face))\n```\n\n## Semantic faces\n\n![Architecture](img/architecture.png)\n\nIn addition to the \"elemental\" faces, `elemental-theme` also defines\nsome utility faces (called \"semantic\" faces). For an example,\n`org-link` and `markdown-link-face` both inherit the same \"semantic\"\nface `elemental-reference`, which is then derived from some\n\"elemental\" faces (`underline` specifically).\n\n\"semantic\" faces provides an abstraction layer of faces based on\nsemantics (meanings), which helps adding support to new packages in a\nconsistent way, and keep the theme organized (kinda like \"molecule\"s\nin \"Atomic Design\").\n\nMoreover, `elemental-theme` does not inhibit users to modify these\n\"semantic\" faces. You may redefine how `reference` should look like,\nif you want (make it italic, instead of underlined, for an example).\n\nFollowing faces are called \"semantic\" in this theme.\n\nYou may use `M-x describe-face` for more detailed descriptions of each\nfaces.\n\nBasic:\n\n- `elemental-caution`\n- `elemental-diminished`\n- `elemental-highlight`\n- `elemental-inappropreate`\n- `elemental-incorrect`\n- `elemental-key`\n- `elemental-match`\n- `elemental-match-interactive`\n- `elemental-reference`\n- `elemental-selected`\n- `elemental-annotation`\n\nDifferences (NOT only for the `diff-mode`™️):\n\n- `elemental-diff-added`\n- `elemental-diff-changed`\n- `elemental-diff-refine-added`\n- `elemental-diff-refine-changed`\n- `elemental-diff-refine-removed`\n- `elemental-diff-removed`\n\nFilenames:\n\n- `elemental-file-executable`\n- `elemental-file-name`\n- `elemental-file-special`\n\nIndicators:\n\n- `elemental-indicator-error`\n- `elemental-indicator-info`\n- `elemental-indicator-success`\n- `elemental-indicator-warning`\n\nNested structures:\n\n- `elemental-level-1`\n- `elemental-level-2`\n- `elemental-level-3`\n- `elemental-level-4`\n- `elemental-stage-1`\n- `elemental-stage-higher`\n- `elemental-stage-negative`\n\nMarkups:\n\n- `elemental-markup-code`\n- `elemental-markup-table`\n\nCodes:\n\n- `elemental-syntax-builtin`\n- `elemental-syntax-literal`\n- `elemental-syntax-symbol`\n- `elemental-syntax-type`\n\nUI components:\n\n- `elemental-ui-component`\n- `elemental-ui-component-diminished`\n- `elemental-ui-component-transparent`\n- `elemental-ui-ghost`\n- `elemental-ui-prompt`\n\n## Policies\n\nPlease follow the policies below when adding support to new packages.\n\n### Consistent\n\nAll supported faces (except for the \"elemental\" and \"semantic\" faces)\nmust be derived from exactly one \"semantic\" face (or the `default`\nface). We neither put any styles directly to a face, nor make more\nthan two inheritances for a single face.\n\nWhen a face inherits a semantic face, the face's \"meaning\" must fit\nthe description of the semantic face (i.e. You CANNOT use\n`elemental-selected` just for its style. You CAN use\n`elemental-selected` face only if it's actually a selected item).\n\nIf you find that there's no suitable semantic face for the purpose,\nit's okay to add a semantic face by deriving some \"elemental\" or\n\"semantic\" faces. Note that we do not put any styles directly to a\nsemantic face.\n\n### Distinguishable\n\n`elemental-theme` defines MANY semantics faces, and it's nearly\nimpossible to put unique styles to all the semantic faces. So in\n`elemental-theme`, it's okay to put the same style to more than one\nsemantic faces (i.e. it's okay that `elemental-markup-table` and\n`elemental-syntax-literal` look the same).\n\nBut, if two different semantic faces (often) appear in the same buffer\n(or the same UI element, like popups), it's not okay to put the same\nstyle to these faces. For an example, `elemental-markup-code` and\n`elemental-markup-table` are both used to highlight markup files. So\nthey should look different (to avoid ambiguity).\n\n## Related works\n\n- `base16-emacs`\n- `emacs-color-theme-solarized`\n\nThey both have ability to generate a color theme from a color palette,\nso that they can act like \"color theme framework\"s.\n\n`elemental-theme` is, unlike these theme frameworks, just a \"color\ntheme\" which is well organized with the built-in inheritance\nmechanism. So `elemental-theme` can be customized dynamically (without\nneed to \"re-generate\" the theme when you make changes), and works well\nwith not just colors but any face attributes like `bold`, `italic`\netc.\n\n`elemental-theme` also has an abstraction layer called \"semantic\"\nfaces, which enhances extensiblity \u0026 customizablity in a consistent\nway.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzk-phi%2Felemental-theme","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzk-phi%2Felemental-theme","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzk-phi%2Felemental-theme/lists"}