{"id":20672116,"url":"https://github.com/workarea-commerce/workarea-theme","last_synced_at":"2026-04-18T08:31:57.201Z","repository":{"id":56898460,"uuid":"203658802","full_name":"workarea-commerce/workarea-theme","owner":"workarea-commerce","description":null,"archived":false,"fork":false,"pushed_at":"2020-01-03T18:07:54.000Z","size":58,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-12-06T17:48:47.621Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/workarea-commerce.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-08-21T20:23:42.000Z","updated_at":"2020-01-03T18:07:54.000Z","dependencies_parsed_at":"2022-08-21T02:20:43.415Z","dependency_job_id":null,"html_url":"https://github.com/workarea-commerce/workarea-theme","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/workarea-commerce/workarea-theme","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workarea-commerce%2Fworkarea-theme","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workarea-commerce%2Fworkarea-theme/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workarea-commerce%2Fworkarea-theme/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workarea-commerce%2Fworkarea-theme/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/workarea-commerce","download_url":"https://codeload.github.com/workarea-commerce/workarea-theme/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workarea-commerce%2Fworkarea-theme/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31962073,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T00:39:45.007Z","status":"online","status_checked_at":"2026-04-18T02:00:07.018Z","response_time":103,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2024-11-16T20:32:05.238Z","updated_at":"2026-04-18T08:31:57.164Z","avatar_url":"https://github.com/workarea-commerce.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"Workarea Theme\n================================================================================\n\nThis plugins provides infrastructure for theme development and use on the Workarea platform.\n\nWorkarea Themes\n--------------------------------------------------------------------------------\n\nA Workarea theme is a specialized type of Workarea plugin.\nThemes specifically customize the appearance of the Workarea platform.\nThemes allow for re-use of storefront code, helping to jump-start front-end work\nfor an implementation.\nA theme may be used as a starting point for front-end development, or as a\ncomplete storefront UI.\n\nInstalling a theme in a Workarea application\n--------------------------------------------------------------------------------\n\nInstalling a theme in a Workarea application is like installing any other plugin.\nAdd the theme's gem to your application's gemfile:\n\n```ruby\n  source 'https://gems.weblinc.com' do\n    gem 'workarea-your_theme_name'\n  end\n```\n\nThen run `bundle install` and restart your application.\n\nSome themes may need extra configuration. Check the README.md for the theme you\nare using to see if any further configuration is necessary.\n\nConfiguring a theme\n--------------------------------------------------------------------------------\n\nAll themes include a `config/initializer/theme.rb` file, which provides options\nfor configuration within the Workarea application.\nTypically themes allow configuration for color schemes and font families.\n\nAn example of a Workarea theme configuration file:\n\n```ruby\nWorkarea.configure do |config|\nconfig.theme = {\n  color_schemes: [\"one\", \"workarea\", \"midnight\"],\n  color_scheme: \"one\",\n  font_stacks: {\n    roboto: '\"Roboto\", \"HelveticaNeue\", \"Helvetica Neue\", sans-serif',\n    lora: '\"Lora\", \"Times New Roman\", \"Georgia\", serif',\n    hind: '\"Hind\", Helvetica, Arial, sans-serif',\n    source_serif_pro: '\"Source Serif Pro\", \"Times New Roman\", Georgia, serif',\n    muli: '\"Muli\", Helvetica, Arial, sans-serif',\n    playfair_display: '\"Playfair Display\", \"Times New Roman\", Georgia, serif'\n  },\n  primary_font_family: \"roboto\",\n  secondary_font_family: \"lora\"\n}\nend\n```\n\nApproaches to using a theme\n--------------------------------------------------------------------------------\n\nThere are 2 ways to use a Workarea theme.\n\n1. Installing the theme as a gem in your application, similar to other plugins.\n2. As a development tool by running the `starter_store` generator to import a\n    theme's files to your application.\n\n### Gem vs. Development tool approach\n\nUsing a Workarea theme as a gem is the quickest way to apply a theme to a Workarea\napplication. The benefit of running a theme as a gem is getting bug-fixes and upgrades\nfrom the theme in patch releases.\n\nUsing a theme as a development tool is an alternative way to use a Workarea theme.\nRather than running the theme as a plugin; all of the theme's files, dependencies,\nand configurations are copied in to your application. This is done by running the\n`starter_store` generator from your host application. This approach allows greater\nflexibility in development, however it removes you from the direct upgrade path\nfor the theme. This means you will need to use the Workarea upgrade tool to apply\npatches and upgrades as they are released for the theme.\n\nThe development tool approach is most useful if:\n\n- You plan to customize the application heavily using the theme as a starting point.\n- You need to remove a dependency of the theme.\n  - For example a theme may depend on workarea-reviews, but your implementation uses\n    a 3rd party review system. The only way to use a theme and remove one of its\n    dependencies is by installing the theme using the `starter_store` generator.\n\n### Using a theme as a development tool\n\nTo prepare for installing a theme as a starter store you must add the theme to\nyour application gemfile and run `db:seed`. Once you have the theme running in your\napplication run the `starter_store` generator\n\n```bash\nbundle exec rails g workarea:starter_store\n```\n\nDuring the execution of this generator you will be prompted to make decisions\nre. overriding existing files in your application. Use the Ynaqdh interface\nto make decisions on a per-file basis. I have found that 'n' is typically the\npreferable choice, with the exception of locales/en.yml\n\nAfter the generator is run you should:\n\n1. Run bundle install.\n2. Confirm that your application is running and is styled as expected.\n3. Remove the now commented-out theme from your gemfile.\n4. Run the full test suite and ensure nothing is failing.\n5. Commit your changes and open a pull-request.\n\n#### Appended files\n\nAppends, and append removals will still be handled via the imported appends.rb\ninitializer. It is recommended that you review the contents of this file and\nupdate your host application where appropriate to include these appended files\nas normal, removing them from appends.rb. This is especially advisable for Sass\nand JS assets which can easily be added to your application manifests.\n\nUpgrading a themed application\n--------------------------------------------------------------------------------\n\nIf you have installed your theme using the `starter_store` generator the upgrade\npath is the same as any other application. Be sure to use the [Workarea upgrade tool](https://stash.tools.weblinc.com/projects/WL/repos/workarea-upgrade/browse) when\nupgrading your application\n\nIf your application is using a theme as a plugin you should follow these steps:\n\n1. Check whether your theme has already been upgraded for compatibility with the\n    version of Workarea you are upgrading to.\n    - If the theme is not yet upgraded contact the theme developer and find out\n    when that will be complete. It is not recommended to upgrade your application\n    until the theme is ready.\n2. Upgrade Workarea and all other plugins first, use the Workarea upgrade tool to\n    create a diff and make the necessary changes in your application.\n3. Update the theme's version in your gemfile to use the latest version that is\n    compatible with your new Workarea version.\n4. Run the upgrade tool against your theme to see if there are further changes\n    that need to be made to files that have been overridden in your application.\n\nOnce all necessary changes highlighted in the diff have been made, tests are\npassing, and your PR has been accepted, your application is upgraded and should\nbe sent to QA for testing. Drink a beer, you've earned it!\n\nMultisite support for themes\n--------------------------------------------------------------------------------\n\nMultisite applications are able to use Workarea themes without many changes to\nthe normal multi-site development workflow.\n\nConfiguration options set in theme.rb should be applied to each instance of\nWorkarea::Site, this allows you to easily apply different color schemes and fonts\nto each site with minimal effort. Skinning a new site for a themed multi-site app\nshould be relatively simple!\n\nIt is not possible to use more than 1 theme per application. This means you cannot\nuse different themes for different sites within a multi-site application. All sites\nmust be based on the same theme, but each can customize away from the theme as necessary.\nFollow the [instructions for working with multi-site applications](https://stash.tools.weblinc.com/projects/WL/repos/workarea-multi-site/browse)\nfor more information about developing multi-site applications.\n\nDeveloping a new Workarea Theme\n--------------------------------------------------------------------------------\n\nTo create a Workarea theme use the _rails plugin new_ command with the Workarea\ntheme template. Follow the instructions for using the [app template](https://developer.workarea.com/workarea-3/guides/app-template),\nwith the following changes.\n\n- Use _rails plugin new_ instead of _rails new_\n- Use the path to _theme\\_template.rb_ (instead of _app\\_template.rb_) as the\n    argument to the _--template_ option\n- Include the _--full_ option when running _rails plugin new_\n\nAfter creating the theme, edit the gemspec file to set relevant metadata.\n\nAlternatively you may use the Workarea CLI to run the new theme generator, if you\nhave the CLI tool installed you can run\n\n```bash\nworkarea new theme path/to/my_theme\n```\n\n### Theme development workflow\n\nOnce you've created your theme engine and edited the gemspec you can start\ndeveloping your theme. Theme development relies heavily on overriding views,\nstylesheets, and javascripts from Workarea Storefront. To jump-start your theme\ndevelopment run the theme override generator to override all of the files you're\nlikely to need in your theme.\n\nTo use the theme override generator run\n\n```bash\nbin/rails generate workarea:theme_override\n```\n\nThis will override every view file, along with most Sass and JS files from\nworkarea-storefront. The generator also commits these overrides and stores the\ncommit SHA in `lib/workarea/theme/override_commit`. This file is used by the\nWorkarea `theme_cleanup` rake task and should not be deleted.\n\nHaving overridden most of the files you will need to develop your theme, you are\nnow ready to start implementing your designs. Should you need to override other\nfiles from Storefront, or another plugin, you should use the [Workarea override\ngenerator](https://developer.workarea.com/workarea-3/guides/overriding).\n\nOnce you have implemented your theme you should run the Workarea `theme_cleanup` rake\ntask. This will remove any files in `/app` that have not changed since you ran the\ntheme_override generator. To execute `theme_cleanup` run:\n\n```bash\nbin/rails workarea:theme_cleanup\n```\n\nBe sure to check the files that have been removed, and test that your theme runs\nand looks correct before committing this change.\n\nOnce your theme is cleaned up you're done, congratulations! Now head over to the\n[Workarea plugin documentation](https://developer.workarea.com/workarea-3/guides/plugins-overview)\nto learn how to release your theme for use!\n\n### Theme requirements\n\nIn order for your theme to be registered correctly within the host application it\nmust depend on workarea-theme and have the following include in your plugin's\nengine.rb file:\n\n```ruby\n  include Workarea::Theme\n```\n\nThis is necessary for the `starter_store` generator to work.\n\nIn addition your theme must:\n\n- Include a theme.rb initializer.\n- Allow the host application to configure the color scheme.\n- Allow the host application to configure fonts.\n\nThe theme_template will take care of setting these things up for you, be sure to\nfollow the instructions for creating a new Workarea theme to ensure your theme is\nconfigured properly.\n\nIt is recommended that your theme's README include the following information:\n\n- Optimal image sizes.\n- Compatible Workarea plugins and dependencies.\n- Browser support, preferably supplemented with a browserlist file in the theme's\n    root directory.\n- Instructions for any additional configuration or features specific to your theme.\n\n### Theme plugin dependencies\n\nYour theme may include dependencies on other Workarea plugins. This allows you to\nship a theme with support for popular functionality out of the box, and to benefit\nfrom pluginized UI components and functionality.\n\nTo add support for another plugin, first add it to your theme's gemspec like this:\n\n```ruby\ns.add_dependency 'workarea-swatches', '1.0.0'\n```\n\nNext you will need to override the relevant files from the plugin to your theme.\nYou should use the [workarea override generator](https://developer.workarea.com/workarea-3/guides/overriding) to do this.\nOnce you have overridden all of the necessary files you can adjust styles, markup,\nand functionality as required to meet your requirements.\n\n_Note:_ dependencies of a theme cannot be removed when using\nthe theme as a gem, so it is best to keep dependencies to a minimum. The only way\nto remove a theme's dependencies within a host application is to use the `starter_store`\ngenerator, then remove the unwanted dependency from the application gemfile along\nwith any related app files (views, styles etc.).\n\n### Maintaining your theme\n\nA theme is like a baby, you spend a while making one, then you have a lifetime\nof taking care of it.\n\nMaintaining your theme means fixing bugs as they come in, and keeping your theme\nup to date with the latest versions of Workarea. If your theme is not kept up to\ndate you will cause great pain and sadness for developers that have used your theme\nin their applications. You might prevent them from being able to take upgrades.\n\n#### Upgrading for minor-version compatibility\n\nUpgrading your theme for compatibility with Workarea is important. At a minimum\nall themes should be upgraded with the latest changes in each new minor version\nof Workarea.\n\nTo upgrade your theme follow these steps:\n\n1. Read both the release notes on developer.workarea.com and the release announcement\n    on discourse.\n    - Discourse includes release notes for plugins, ensure any plugin dependencies\n    are upgraded too!\n2. Create a new host app to use for the upgrade.\n3. Install your theme, seed the app, and make sure it’s running as expected.\n4. Install the workarea-upgrade gem.\n5. Use the `starter_store` generator to clone your theme in to your new host\n    application.\n6. Run the workarea_upgrade command, first checking the report for your upgrade,\n    then generating a diff.\n7. The upgrade report should help you estimate how much time your upgrade will take.\n8. Step through your diff making all the necessary changes to your theme.\n9. Load your theme and the latest version of Workarea in a different host app.\n10. Ensure the app loads, resolve any errors you encounter.\n11. Check every view that you changed as part of the diff.\n12. If styles or JS functionality were changed or added you should ensure these\n    are working as intended at this point.\n13. Commit your changes and open a PR.\n\nGood work soldier! Your Workarea theme is up-to-date. Once your PR is approved,\nand changes pass QA you can release your theme's new minor version to the gem server.\n\nWorkarea Commerce Documentation\n--------------------------------------------------------------------------------\n\nSee [https://developer.workarea.com](https://developer.workarea.com) for Workarea Commerce documentation.\n\nLicense\n--------------------------------------------------------------------------------\n\nWorkarea Theme is released under the [Business Software License](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fworkarea-commerce%2Fworkarea-theme","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fworkarea-commerce%2Fworkarea-theme","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fworkarea-commerce%2Fworkarea-theme/lists"}